Skip to content

QUICK_START.en.md

Latest commit

 

History

History
144 lines (98 loc) · 4.58 KB

QUICK_START.en.md

File metadata and controls

144 lines (98 loc) · 4.58 KB

Quick Start Guide

Get from zero to your first contribution in under 10 minutes.

Prerequisites

Tool Version Install
Node.js see .nvmrc nodejs.org
pnpm latest npm i -g pnpm
nvm any UNIX / Windows
git any git-scm.com

1. Clone and install

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

2. Start Storybook

pnpm run storybook

Storybook opens at http://localhost:6006. This is your development environment — every component lives here.

3. Find something to work on

Go to the GitHub Project board and pick an open issue from the Todo column.

First time? Look for issues tagged layer: atom with category: component — these are self-contained and well-defined.

Before writing code, make sure the spec is defined and the issue has the status:approved label. Only then run START WORK:

  • assign the issue to yourself;
  • move it to In progress;
  • record the branch and worktree plan.

4. Create your branch

If the task comes from an issue, use issue-derived naming:

git checkout -b feat/123-your-component
# or
git checkout -b fix/128-short-description

If you use a worktree, use the matching sibling path:

../design-system-feat-123-your-component

Branch naming follows Conventional Commits:

  • feat/ — new component or feature
  • fix/ — bug fix
  • a11y/ — accessibility improvement
  • tokens/ — design token change
  • docs/ — documentation only

5. Build your component

Every component follows the 6-file pattern. Use CONTRIBUTOR-FLOW.en.md as the canonical workflow and create it manually under the correct atomic layer:

src/components/atoms/your-component/
├── types.ts                   # Types + JSDoc controls + CVA variants
├── useYourComponent.ts        # Container layer — logic, state, handlers
├── YourComponent.tsx          # Presentational layer — JSX only
├── YourComponent.test.tsx     # Hook and component behavior tests
├── YourComponent.stories.tsx  # Storybook documentation
└── index.ts                   # Public exports

Read CONTRIBUTOR-FLOW.en.md for the full workflow and GUIDELINES.en.md for architecture rules before writing code.

6. Run tests

pnpm test

All tests must pass before opening a PR. If you're adding a new component, add tests too.

7. Open a Pull Request

Push your branch and open a PR against main:

git push origin feat/123-your-component

Then go to GitHub → your branch → Compare & pull request.

  • Use the PR template — fill in every section
  • Link the issue in the summary (Closes #123)
  • Add screenshots if there are visual changes
  • Clean MCP artifacts before commit/review: rm -rf .playwright-mcp page-*.png page-*.jpeg *.md.playwright-output

The project lead reviews and merges. The task moves to Done only through END WORK after the PR is merged or explicit approval is given.

Commit message format

We use Conventional Commits. Git hooks will reject commits that don't follow this format.

feat(button): add loading state variant
fix(switch): forward aria-label prop correctly
docs(modal): add usage examples to Storybook
fix(a11y): improve input focus ring visibility
chore(tokens): update spacing token docs

Format: <type>(<optional scope>): <description> (scope is optional)

Common types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.

Use a11y, tokens, or infra as scopes, not as custom types.

Using AI agents (optional)

This project supports opencode with pre-configured context. If you use it:

opencode

The agent automatically loads the project rules from .atl/AGENTS.md — no manual setup needed. Read CONTRIBUTING.en.md for the full AI workflow.

Need help?