A calm, warm, deeply-accessible product surface.

Introduction

The system is lifted directly from member-app/app/globals.css so there is zero drift between the runtime theme and design review. Tokens are HSL CSS custom properties; components are shadcn primitives wrapped in Doro-specific behavior. Everything flows through a single Tailwind preset.

Packages

Four sibling packages. Dependency order flows left to right: tokens → icons → ui → docs.

Color

All surfaces are driven by HSL CSS custom properties declared in @doro/design-tokens/tokens.css. Toggle light/dark in the sidebar — every swatch below reflects the current theme.

Typography

Fraunces for editorial display. Inter Tight for interface. JetBrains Mono for code. Fluid size ramp, never smaller than 13px in product UI.

Spacing & radius

4px base grid, Tailwind-default. Radius tokens flow from --radius (0.75rem) — bump that one variable to reshape the system.

Motion

Short, purposeful motion. Duration under 300ms unless there's narrative reason. All motion is auto-disabled by prefers-reduced-motion.

Buttons

Primary, secondary, outline, ghost, destructive, link. Size ramp: sm, default, lg, icon.

Forms

Input, Textarea, Label, Checkbox, Radio, Switch. All bound to --ring for focus outline — WCAG AA against the warm background.

Feedback

Alerts, badges, progress. Low-noise states — we don't surface "success" toasts for everyday writes.

Data display

Cards, avatars, simple tables. The dashboard layout in member-app is composed entirely from these primitives.

shadcn primitives

The full roster exported from @doro/design-ui/components/ui. Each has a matching Storybook story; tokens flow through the same HSL variables.

import {DoroDatePicker} from '@doro/design-ui';

<DoroDatePicker
  value={date}
  onChange={setDate}
  placeholder="Appointment date"
/>

cd core/design/ui
npx shadcn@latest add <primitive>        # writes components/ui/<name>.tsx

# Then:
# 1. add to components/ui/index.ts
# 2. write a story under stories/
# 3. bump package.json deps if the primitive pulls new Radix packages

Monorepo structure

The design system lives alongside other core/* packages. Apps are siblings of core/, not nested.

Consuming packages

Three lines of wiring — package.json, next.config.mjs, tailwind.config.ts.

1. Link as file: dependencies

// member-app/package.json
{
  "dependencies": {
    "@doro/design-tokens": "file:../core/design/tokens",
    "@doro/design-icons":  "file:../core/design/icons",
    "@doro/design-ui":     "file:../core/design/ui"
  }
}

2. Transpile in Next

// member-app/next.config.mjs
export default {
  transpilePackages: [
    '@doro/design-tokens',
    '@doro/design-icons',
    '@doro/design-ui',
  ],
};

3. Extend Tailwind with the preset

// member-app/tailwind.config.ts
import designPreset from '@doro/design-tokens/tailwind-preset';

export default {
  presets: [designPreset],
  content: [
    './app/**/*.{ts,tsx}',
    '../core/design/ui/src/**/*.{ts,tsx}',
  ],
};

4. Import the base CSS once

// member-app/app/layout.tsx
import '@doro/design-tokens/tokens.css';
import '@doro/design-tokens/styles.css';

5. Use primitives

import {Button, Card, CardTitle} from '@doro/design-ui';
import {IconCheck} from '@doro/design-icons';

export function Confirm() {
  return (
    <Card>
      <CardTitle>All set</CardTitle>
      <Button><IconCheck /> Done</Button>
    </Card>
  );
}

shadcn upgrade strategy

shadcn components live inside @doro/design-ui, not vendored into every app. The rules below keep them upgradeable.

cd core/design/ui
npx shadcn@latest add dropdown-menu

// components/doro-button.tsx
import {Button, type ButtonProps} from './ui/button.js';

export function DoroButton(props: ButtonProps) {
  return <Button className="doro-warm-shadow" {...props} />;
}

Release flow

Independent versioning via release-please. Identical to every other core/* package.

1. Commit with conventional-commit messages targeting a design package: feat(design-ui): add DropdownMenu primitive
2. release-please opens a PR bumping that package's version and updating its CHANGELOG.md.
3. Merging tags a release — design-ui-v0.3.0, design-tokens-v0.2.1, etc.
4. Cloud Build triggers on the tag pattern and deploys the package's artifact (Storybook for ui, static site for docs). Token and icon releases are library-only — no deploy.
5. Consuming apps update their file: link and re-run npm install. Build-gating in the app's CI catches breaking API drift before merge.

Accessibility

WCAG 2.2 AA is the floor, not the ceiling. Every token pair below is computed live from @doro/design-tokens. Pass / fail is marked against WCAG AA for normal text (4.5:1).

Contributing

See core/design/CONTRIBUTING.md for the long version. The short version:

1. Does the change need new tokens? If yes, PR tokens/ first.
2. Is this an unmodified shadcn primitive? Use the CLI — don't hand-author.
3. Is this a Doro-specific tweak to a shadcn primitive? Wrap it in a doro-* component.
4. Every new primitive or wrapper ships with a Storybook story and, where it affects composition, a section here in design-docs.
5. Run task verify from core/design/ before opening the PR.