README.en.md

Stack-and-Flow Design System

What this project is

Stack-and-Flow is an educational, accessible design system that can be published as an npm package, built with React, TypeScript, Tailwind CSS v4, Radix UI primitives, CVA, Storybook, and Vite.

The goal is to learn and practice how a real component library is built: tokens, architecture, living documentation, tests, accessibility, visual review, and a GitHub Projects contribution workflow.

Tech stack

Quick start

git clone https://github.com/Stack-and-Flow/design-system.git
cd design-system
nvm use
pnpm install
pnpm run storybook

Storybook is available at http://localhost:6006.

Public demo: sf-design-system.netlify.app

Component architecture

Every component lives in src/components/{atoms|molecules|organisms}/{kebab-name}/ and uses the mandatory 6-file pattern:

src/components/atoms/button/
├── types.ts              # Props, public types, and CVA variants
├── useButton.ts          # Logic, state, handlers, aria, and computed className
├── Button.tsx            # Presentational JSX; consumes the hook
├── Button.test.tsx       # Hook tests and component behavior tests
├── Button.stories.tsx    # Storybook autodocs, args, variants, and states
└── index.ts              # Named component export + type exports

Base rules:

• Use type, never interface.
• No explicit any.
• CVA lives in types.ts.
• The component .tsx contains no logic and no CVA calls.
• Public imports/exports are named, for example import { Button } from '@stack-and-flow/design-system'.
• Storybook uses JSDoc above const meta and above every export const StoryName.
• Do not use parameters.docs.description.component.

Contributing

This project uses GitHub Issues + GitHub Projects as the source workflow.

Short path:

1. Pick an issue from the Project Board.
2. Before implementing, verify that the spec is defined and the issue has the status:approved label.
3. Only then run START WORK:
   • assign the issue to the contributor;
   • move the Project item to In progress;
   • record the branch and worktree.
4. Use issue-based branch names:
   • feat/{issue-number}-{slug}
   • fix/{issue-number}-{slug}
   • docs/{issue-number}-{slug}
5. If you need a worktree, create it as a sibling of the repo:
   • ../design-system-{type}-{issue-number}-{slug}
   • not under /tmp, unless explicitly requested.
6. Implement with the 6-file pattern.
7. Run tests/build/visual review as needed.
8. Before commit/review, clean MCP artifacts:

rm -rf .playwright-mcp page-*.png page-*.jpeg *.md.playwright-output

9. When closing, run END WORK only with a merged PR or explicit maintainer/user approval, plus validation evidence.

Recommended docs:

• Quick Start
• Contributor Flow
• Contributing
• Guidelines
• Design Reference
• Components Reference

Golden rules

• We only use Radix UI primitives as unstyled base primitives.
• We do not use shadcn as a component source or configuration layer.
• Use tokens from src/styles/theme.css; do not hardcode colors, fonts, or spacing.
• If a token is missing, propose adding it centrally before using raw values.
• Accessibility is mandatory: accessible name, keyboard behavior, visible focus, contrast, reduced motion.
• Code, comments, Storybook, and public names are in English.

Useful scripts

pnpm run storybook       # Local Storybook
pnpm run test            # Vitest
pnpm run test:coverage   # Coverage
pnpm run build           # Library build + types

Playwright MCP and AI visual audit

Playwright MCP is optional infrastructure for AI agents. It may generate artifacts such as .playwright-mcp/, page-*.png, page-*.jpeg, or *.md.playwright-output.

These files are never committed. Before commit or review:

rm -rf .playwright-mcp page-*.png page-*.jpeg *.md.playwright-output

Resources

• Live Storybook: sf-design-system.netlify.app
• Project Board: GitHub Projects
• Deepwiki Wiki: deepwiki.com/Stack-and-Flow/design-system

Educational project

This repository is open to collaboration. It is a good place to learn design systems, React, TypeScript, component architecture, accessibility, Storybook, and package publishing.

Contact

---

⭐ If you find this project useful, consider giving it a star on GitHub ⭐