SSW Design System

A React component library powered by Storybook, Tailwind CSS, and shadcn-style primitives.

Goals

• Provide a consistent UI foundation across SSW projects.
• Keep component behavior and visual standards documented in Storybook.
• Ship reusable components that consumer apps can install.

Tech stack

• React 19 + TypeScript
• Vite
• Storybook 10
• Tailwind CSS 4
• Biome
• Chromatic

Getting started

pnpm install
pnpm storybook

Scripts

| Script | Purpose | | --- | --- | | pnpm dev | Run local Vite app playground | | pnpm storybook | Run Storybook | | pnpm storybook:build | Build Storybook static output | | pnpm storybook:test | Run Storybook Vitest project | | pnpm lint | Run Biome checks and apply safe fixes | | pnpm format | Format repository with Biome | | pnpm chromatic | Publish Storybook to Chromatic | | pnpm changeset | Create a versioning/changelog entry | | pnpm version-packages | Apply pending changesets to package version/changelog | | pnpm release | Publish package(s) to npm via Changesets |

Story organization

• src/stories/ui/atoms/*.{stories.tsx,mdx}: base UI primitive stories/docs mapped from src/components/ui.
• src/stories/ui/molecules/*.{stories.tsx,mdx}: composed components built from atoms.
• src/stories/ui/organisms/*.{stories.tsx,mdx}: larger feature-level sections (for example Login blocks).
• src/stories/foundations/*.stories.tsx and *.mdx: design tokens and system-level guidance.
• Story titles follow:
  • Foundations/...
  • UI/Atoms/...
  • UI/Molecules/...
  • UI/Organisms/...

What are foundational stories?

Foundational stories document system-wide rules rather than one component API. They include tokens (color, spacing, typography), theme behavior, accessibility rules, and composition guidelines shared across many components.

Component boundaries

• src/components/ui: reserved for generated/vendor-style shadcn primitives. Avoid manual edits here.
• src/components: custom SSW components and wrappers.
• src/components/ssw (recommended): shared SSW abstractions built on top of src/components/ui.
• If you need styling or behavior changes to a primitive (for example Button variants), build a wrapper component in src/components/ssw rather than modifying src/components/ui/button.tsx.

Chromatic token setup

1. Copy .env.example to .env.
2. Set CHROMATIC_PROJECT_TOKEN in .env for local publishing.
3. Set CHROMATIC_PROJECT_TOKEN as a GitHub Actions repository secret for CI publishing.

Release workflow (Changesets)

This package is published through a Changesets-driven release PR workflow.

1. After code changes, run pnpm changeset.
2. Choose patch, minor, or major.
3. Write a consumer-facing changelog summary.
4. Commit the generated .changeset/*.md file with your change.
5. Merge your feature PR to main.
6. GitHub Actions creates or updates a Release PR containing version/changelog updates.
7. Merge the Release PR to apply version/changelog updates.

Publishing status

• Publishing is currently disabled ("private": true in package.json and no publish step in .github/workflows/release.yml).
• Re-enable publishing only after deciding the private registry target and token strategy.

Team workflow

1. Build wrappers/custom components in src/components or src/components/ssw.
2. Add or update *.stories.tsx in src/stories/ui/* or src/stories/foundations.
3. Add or update an MDX page for each component in the same src/stories/ui/* level.
4. Verify docs and controls in Storybook.
5. Run pnpm lint and pnpm storybook:test.
6. Create and commit a changeset (pnpm changeset) for user-facing changes.
7. Open a PR and rely on Chromatic for visual review.

Using with AI agents

The design system ships an agent skill (skills/ssw-design-system/) that teaches AI coding agents (Claude Code, claude.ai, etc.) how to integrate the system into a consuming project — choosing between the npm package and the shadcn registry, wiring styles and fonts, and theming via tokens.

The skill is a single self-contained markdown file (easy to inspect before use), published on the public docs site (no repo access needed):

• Skill: https://design.ssw.com.au/skill/SKILL.md
• Packaged for claude.ai: https://design.ssw.com.au/skill/ssw-design-system.skill

Ways to use it:

• Zero-install (any agent with web access) — paste this to the agent:

  Set this project up with the SSW design system. Fetch and follow https://design.ssw.com.au/skill/SKILL.md

• Claude Code: save SKILL.md into the project's .claude/skills/ssw-design-system/ (or ~/.claude/skills/… for all projects).
• claude.ai / Cowork: upload the .skill file (Settings → Capabilities → Skills) — it's a zip of the same single SKILL.md, packaged because the upload requires that format.