Skip to content

README.md

Latest commit

 

History

History
250 lines (190 loc) · 11.1 KB

README.md

File metadata and controls

250 lines (190 loc) · 11.1 KB
Raw
Nebari horizontal logo mark

Nebari design

🎨 This repository is a shadcn component registry styled with the Nebari brand, and the home of the Nebari project's design assets.

Browse every component, with docs and live examples, in the deployed Storybook: https://nebari-dev.github.io/nebari-design/.

Component registry

Components are styled with the Nebari brand and can be installed into any shadcn-based project.

Install

Register the @nebari namespace once in your project's components.json so the shadcn CLI knows where to resolve @nebari/<name> items:

{
  "registries": {
    "@nebari": "https://nebari-dev.github.io/nebari-design/r/{name}.json"
  }
}

Then add any item:

npx shadcn add @nebari/<name>

For example, to install the shared cn() utility and the Nebari theme tokens:

npx shadcn add @nebari/utils
npx shadcn add @nebari/theme

Installing a component automatically pulls in its registry dependencies — adding @nebari/button also installs @nebari/utils, @nebari/spinner, and @nebari/theme if they aren't present yet.

What's in the registry

The manifest in registry.json is the source of truth for installable items; each one is documented in Storybook. The catalog currently covers:

  • Foundations — utils (the cn() helper), theme (brand color tokens and radius for light and dark modes), and claude-skill (see below).
  • Hooks — use-theme-preference (a hook + ThemeProvider that persists a light/dark/system preference and follows the OS).
  • Forms & inputs — button, button-group, input, textarea, label, field, checkbox, radio-group, switch, slider, select.
  • Overlays & menus — dialog, drawer, dropdown-menu, tooltip.
  • Navigation — navigation-menu, breadcrumb, tabs.
  • Feedback & display — alert, badge, card, table, code-block, spinner.

Fonts

The theme tokens in registry/nebari/globals.css set --font-sans to Geist and --font-mono to IBM Plex Mono. The theme only references these families — install the webfonts in your app so they actually load:

npm i @fontsource-variable/geist @fontsource/ibm-plex-mono

Then import them once at your app's entry point:

import '@fontsource-variable/geist';
import '@fontsource/ibm-plex-mono/400.css';
import '@fontsource/ibm-plex-mono/500.css';

Skip this and the tokens gracefully fall back to the system sans-serif / monospace stacks.

Claude Code skill for consumers

If you build your app with Claude Code, install the Nebari UI skill into your project so the assistant knows how to set up the registry, which components exist, and how to use and theme them:

npx shadcn add @nebari/claude-skill

This drops a skill at .claude/skills/nebari-ui/SKILL.md in your repo (distinct from the contributor authoring skill below, which lives in this repo). Once installed it auto-triggers on requests like "add the nebari button" or "build a form with nebari components", and stays current through the same shadcn add flow as the components themselves.

Registry layout

Path Purpose
registry.json Registry manifest — the source of truth for installable items.
registry/nebari/ui/ UI components (registry:ui).
registry/nebari/hooks/ Shared non-visual logic, e.g. theme state (registry:hook).
registry/nebari/lib/ Shared library code, including the cn() helper (registry:lib).
registry/nebari/globals.css Tailwind v4 @theme token mapping.
registry/nebari/skills/ Consumer-facing Claude Code skills (registry:file).
public/r/ Built, installable JSON artifacts produced by build:registry.

Contributing a component

This repo ships a Claude Code skill at .claude/skills/nebari-component/ that encodes the house recipe for adding a component to the registry — the component file pattern (cva variants, data-slot attributes, cn() merging, Base UI render-prop composition), the registry.json entry shape, story and test templates, and the verification gate. Any contributor using Claude Code gets it automatically; invoke it with /nebari-component or just ask to "add a <X> component to the registry".

Every component change must pass the verification gate before it's done:

bun run build:registry   # registry.json is valid and the item builds into public/r
bun run check            # biome lint + format (use check:fix to auto-fix)
bunx tsc --noEmit        # types pass
bun run test             # unit tests pass

Design-to-code with Figma

Because the Nebari brand and components originate in design, we recommend installing the Figma MCP server when working on registry components with an AI coding assistant. It lets the assistant read a Figma frame's layout, styles, and design tokens directly, so generated components stay faithful to the source design and aligned with the Nebari brand colors and fonts. Pair it with the /nebari-component skill above: pull the design context from Figma, then scaffold the component using the house recipe.

Development

This project uses Bun, TypeScript, and Tailwind CSS v4. The @/* path alias resolves to registry/nebari.

bun install              # install dependencies
bun run build:registry   # build the registry into public/r
bun run check            # biome lint + format checks (check:fix to auto-fix)

Storybook

Storybook is the local workbench for registry components and the published docs site for this repo. Run it with Bun:

bun run storybook

The dev server runs at http://localhost:6006. Stories live in the top-level stories/ directory, including MDX docs pages and component stories named *.stories.tsx. Storybook uses the same Tailwind v4 setup and @/* alias as the registry source, so imports resolve the same way they do in tests and builds.

Component stories follow a shared controls pattern. Default is the interactive playground and exposes the documented knobs; every other story narrows controls with parameters.controls.include to the props that apply to it — its own subject plus whatever its render leaves live — and uses [] only where nothing is adjustable. Every knob is seeded in the meta args with the component's own default, so controls open as populated widgets rather than click-to-reveal "Set …" buttons; a prop whose unset state is meaningful gets an explicit auto option instead. Consumer composition APIs such as Base UI's render prop remain visible in the props table with control: false, while implementation plumbing is hidden. The full authoring recipe is in .claude/skills/nebari-component/SKILL.md, and tests/story-controls.test.ts enforces the parts that can be checked statically.

The preview loads the Nebari theme tokens and webfonts, enables autodocs for every component, and includes a toolbar switcher for light and dark themes. The custom toolbar is retained instead of adding a second addon switch: its theme global is the single source of truth for both the preview and manager UI. initialGlobals.theme defaults both contexts to light, and .storybook/manager.ts maps updates to manager colors aligned with the semantic tokens in registry/nebari/globals.css. Theme persistence across reloads is not provided. The a11y addon runs axe checks in the UI and fails the Storybook Vitest project when violations are found.

bun run test:storybook   # render every story in Chromium with a11y checks
bun run build:storybook  # build the static Storybook site into public/
bun run build:pages      # build Storybook plus registry JSON for GitHub Pages

The deployed Storybook site is served from https://nebari-dev.github.io/nebari-design/. The installable registry JSON is served from the same Pages build under /r/.

Testing

Components are tested with Vitest, Testing Library, and jsdom. Vitest reuses the same @vitejs/plugin-react, Tailwind, and @ → registry/nebari alias setup as the registry and Storybook, so tests resolve imports exactly like the app does.

bun run test            # run the suite once
bun run test:watch      # watch mode
bun run test:coverage   # run with a coverage report

Test files live in the top-level tests/ directory (mirroring stories/), named *.test.ts / *.test.tsx. Coverage of registry/nebari is enforced at a minimum of 80%.

Design assets

This repository also contains the design assets for the Nebari project.

The assets are available in two formats (PNG & SVG) and in three layouts -- horizontal (also known as landscape format), stacked (which is closer to square), and symbol (which does not include the name and is square), and at least 3 versions (color, white text, & colored background).

You can find the assets in the following locations:

Software used

The application used to create this artwork is Adobe Illustrator.

Acknowledgements

The original designs were created by the very talented Irina Fumarel 💜.

License

Creative Commons Licence
All Nebari design assets by the Nebari dev team are licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.
Based on a work at https://github.com/nebari-dev/nebari-design.