Skip to content
Sulmu UI

Working on this site

This site is an Astro Starlight project in the docs folder of the library repository. It has its own package.json and is not part of the published package.

Run it locally

Section titled “Run it locally”

The site renders the real components from the library build in ../dist, so build the library first.

Terminal window
nvm use
Terminal window
pnpm install && pnpm build
Terminal window
cd docs && pnpm install
Terminal window
pnpm dev

The site is at http://localhost:4321. After changing library code, run pnpm build in the repository root again; the site picks up the new dist.

pnpm build in docs writes the static site to docs/dist, and pnpm preview serves it.

How it is put together

Section titled “How it is put together”
  • Directorydocs
    • astro.config.mjs sidebar, stylesheets, React
    • Directoryscripts
      • gen-props.mjs reads prop types from ../src into src/generated/props.json
    • Directorysrc
      • Directorycontent
        • Directorydocs/ the pages (MDX)
          • …
      • Directoryexamples/ one file per live example
        • …
      • Directorycomponents
        • Example.astro preview frame plus the example’s source
        • PropsTable.astro props of one component
        • IconGrid.tsx the searchable icon grid
      • Directorylib
        • tokens.ts reads ../tokens/*.json for the Foundations pages
      • Directorystyles
        • layers.css cascade layer order (must stay first)
        • docs.css preview frame and token tables
  • The library is linked, not installed. docs/package.json has "@beyul/sulmu-ui": "link:..", so imports resolve through the package’s own exports to ../dist, exactly as they do in an app. React is linked to the copy in the root node_modules so that the library and the site share one React.
  • Examples are real files. <Example src="button/variants"> shows the file src/examples/button/variants.tsx as the code and renders the component passed as its child. The code on the page is the code that runs.
  • Props tables are generated from the hand-written interfaces in ../src/components by scripts/gen-props.mjs, which runs before dev and build.
  • Foundations pages read ../tokens/*.json directly.
  • Dark mode needs no mapping. Starlight sets data-theme on <html>, which is the attribute the library uses.
  • Styles are kept apart. Previews are wrapped in Starlight’s not-content class, which switches off its prose styles inside them. layers.css declares Starlight’s cascade layer before the library’s, so Starlight’s reset cannot override a component.

Add an example to a page

Section titled “Add an example to a page”

  1. Create docs/src/examples/<component>/<name>.tsx with a default export:

    import { Button } from '@beyul/sulmu-ui'
    

    export default function Example() {
      return <Button variant="secondary">Edit</Button>
    }

  2. Import it in the page and wrap it in Example:

    import Example from '~/components/Example.astro'
    import ButtonVariants from '~/examples/button/variants'
    

    <Example src="button/variants">
      <ButtonVariants client:load />
    </Example>

    Add client:load when the example needs JavaScript in the browser (state, popups, event handlers). Leave it out for static examples; they are rendered to HTML at build time.

Example also takes canvas (the lavender page background), flush (no padding), minHeight (room for a popup) and minWidth (for page-wide components; the preview scrolls).

Deploy on Vercel

Section titled “Deploy on Vercel”

The repository has a vercel.json at its root, and a second one in docs, that tell Vercel how to build the site: install the library and the docs, build the library, build the docs, and serve docs/dist. No secrets are needed, because the build installs nothing from the private registry.

Connecting it is done once, in the Vercel dashboard:

  1. Go to Add New… > Project and import the beyul/sulmu-ui repository. If it is not listed, choose Adjust GitHub App Permissions and give Vercel access to it.

  2. Set Root Directory to docs, or leave it empty. Both work: docs/vercel.json is used in the first case and the root vercel.json in the second. With docs, keep Include files outside the root directory in the Build Step switched on (the default).

  3. Leave Framework Preset as Other. The build, install and output settings come from vercel.json; do not override them.

  4. Add no environment variables.

  5. Press Deploy.

  6. After the first deployment, open Settings > Build and Deployment (called General in older dashboards) and set Node.js Version to 24.x, then redeploy.

Every push to main then deploys to production, and every pull request gets a preview URL.