Develop Distributed Package Components

2. Create or modify component styles (ComponentName.css)

• Use CSS custom properties from tokens.css for all themeable values (colors, spacing, radii, etc.)
• Class names use the dds- prefix: dds-componentname, dds-componentname-variant
• Do not use Tailwind in component CSS -- plain CSS with design tokens only

3. Add design tokens (src/styles/tokens.css)

Add tokens in three places within tokens.css:

1. :root -- Light mode (default) values
2. .dds-dark, [data-dds-theme="dark"] -- Explicit dark mode
3. @media (prefers-color-scheme: dark) -- Auto dark mode (OS preference)

The explicit dark mode block and the @media block must have identical values.

Dark mode token guidelines

This library is consumed by apps with various dark backgrounds. Dark mode tokens must work well on a range of dark surfaces, not just one specific shade.

• No pure black or pure white. Use grays with some contrast (e.g. #e5e7eb for text, #4b5563 for borders) rather than #000000 or #ffffff.
• Default to transparent backgrounds unless the component explicitly supports a background color prop.
• For colored backgrounds, use subtle coloring with opacity (e.g. rgba(59, 130, 246, 0.08)) so the component remains visible on various dark surfaces.
• For text/titles on dark, use lighter shades (300-level palette colors like #93c5fd) instead of the full-saturation colors used in light mode.

Token naming convention

Follow the existing pattern: --dds-{component}-{property} or --dds-{component}-{variant}-{property}.

Examples:

--dds-callout-padding: 1.25rem;
--dds-callout-caution-border: #dc2626;
--dds-callout-caution-bg: #fef2f2;

4. Register the component CSS (src/styles/components.css)

Add an @import for the new component CSS file:

@import "../components/ComponentName.css";

This file is the entry point for PostCSS, which bundles all component styles into dist/styles.css.

5. Export the component (src/index.ts)

Add a named export:

export * from './components/ComponentName';

This allows consumers to import directly: import { ComponentName } from '@roadlittledawn/docs-design-system-react'.

6. Write Storybook stories (ComponentName.stories.tsx)

• Import from @storybook/react (Meta, StoryObj)
• Add tags: ['autodocs'] for automatic documentation generation
• Use the parameters.docs.description.component field for component-level docs including "When to Use", "When Not to Use", and "Accessibility" sections
• Write stories that cover: each variant, edge cases (e.g. no title, custom content), and a composite "AllVariants" story for visual comparison
• Use JSDoc comments above each story export to describe it

Example structure:

import type { Meta, StoryObj } from '@storybook/react';
import { ComponentName } from './ComponentName';

const meta: Meta<typeof ComponentName> = {
  title: 'Components/ComponentName',
  component: ComponentName,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: `Description here.

## When to Use
- ...

## When Not to Use
- ...

## Accessibility
- ...
        `,
      },
    },
  },
};

export default meta;
type Story = StoryObj<typeof ComponentName>;

export const Default: Story = {
  args: { /* ... */ },
  parameters: {
    docs: {
      source: {
        code: `<ComponentName prop="value">children</ComponentName>`,
      },
    },
  },
};

7. Bump the package version (packages/react/package.json)

When adding or modifying any component, bump the version in packages/react/package.json following semver:

• Patch (0.x.Y → 0.x.Y+1) — bug fixes, doc-only changes, non-breaking tweaks
• Minor (0.X.0 → 0.X+1.0) — new props, new components, new features (backward-compatible)
• Major (X.0.0 → X+1.0.0) — breaking changes (removed props, renamed components)

"version": "0.12.1"

9. Build and verify

Run from the repo root:

# Build the react package (compiles TS + bundles CSS)
npm run build --workspace=packages/react

# Type-check
npm run type-check --workspace=packages/react

# Visually verify in Storybook
npm run storybook

The Storybook workspace has a prestorybook hook that builds the react package automatically, but it's good practice to build explicitly first to catch errors early.

Storybook auto-discovers stories from packages/react/src/**/*.stories.tsx -- no configuration needed.

8. Update AI-context docs

When adding a new component or modifying an existing component's props:

• Add (or update) the component section in packages/react/USAGE.md — props table and usage examples
• Add (or update) the same component section in storybook/public/llms.txt — keep both files in sync

A pre-commit hook blocks commits that change component files without also updating these docs. Both files follow the same format: import, props table, and basic example.

If you forget, the hook will show:

ERROR: Component files changed without updating AI docs.
  Changed: packages/react/src/components/YourComponent.tsx
  Please update packages/react/USAGE.md and storybook/public/llms.txt.

Key files reference

Common pitfalls

• Forgetting to register CSS in components.css -- the component will render but have no styles in the bundled output.
• Forgetting to export from index.ts -- consumers won't be able to import the component.
• Using hardcoded colors instead of tokens -- breaks dark mode and theme consistency.
• Forgetting the auto dark mode @media block -- users who rely on OS-level dark mode won't get dark styles.
• Using pure black/white in dark mode -- creates harsh contrast that looks bad on various dark backgrounds.
• Not adding new dependency to package.json -- if the component uses a new npm dependency, add it to packages/react/package.json (runtime deps in dependencies, types in devDependencies).
• Missing parameters.docs.source.code on stories -- in production builds, React minifies component.name to a single letter, so the auto-generated source panel shows <c .../> instead of <ComponentName .../>. Every story must have an explicit parameters.docs.source.code string. This applies to all story types: args-only, args+render, and render-only. See Tabs.stories.tsx as the reference implementation.
• Hardcoded text color in story render functions -- Storybook defaults to dark mode (initialGlobals: { theme: "dark" }). Any wrapper element in a render function that contains readable text must use color: "var(--dds-tabs-panel-text)" (or another theme-aware token) rather than relying on the browser default (which is black and unreadable on dark backgrounds). Always set an explicit color on <p>, <div>, and other text-containing wrappers in story renders:

  render: (args) => (
    <p style={{ color: "var(--dds-tabs-panel-text)", fontFamily: "sans-serif" }}>
      Inline text with <ComponentName {...args}>trigger</ComponentName> here.
    </p>
  ),