Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (67 loc) · 7.3 KB

AGENTS.md

File metadata and controls

86 lines (67 loc) · 7.3 KB

Agent Context — Stack-and-Flow Design System

This file is injected automatically as context for all agents working in this project. Keep it minimal — detailed workflows live in skills (skills/).

Project

Stack-and-Flow Design System — open-source, educational React component library.

Key Value
Package @stack-and-flow/design-system
Repo https://github.com/Stack-and-Flow/design-system
Storybook https://sf-design-system.netlify.app/
Guidelines docs/GUIDELINES.md
Contributing docs/CONTRIBUTING.md
Visual Design docs/DESIGN.md

Stack: React 19 · TypeScript strict · Tailwind v4 @theme · Radix UI · CVA · Storybook 8 · Biome · Lefthook · Vite · pnpm 10.34.1

Available tooling:

  • pnpm run build — builds the publishable package and sanitizes generated declarations
  • pnpm run verify:package — builds, packs, and verifies real React 18 + React 19 consumers
  • pnpm run storybook — starts Storybook with hot reload
  • pnpm run test — runs Vitest unit tests
  • pnpm run test:coverage — runs tests with coverage report

Structure

Components live in src/components/{atoms|molecules|organisms}/{kebab-name}/ with exactly 6 files:

File Role
ComponentName.tsx Presentational — JSX only, consumes the hook
useComponentName.ts Logic — state, effects, handlers, CVA class calls
types.ts Types + CVA variants
ComponentName.test.tsx Complete test suite (hook + component tests)
ComponentName.stories.tsx Storybook stories (documentation only, no tests)
index.ts Public API re-exports

Non-negotiable rules

  • type always — never interface
  • Never any — use unknown or narrow properly
  • Never hardcode colors, spacing or fonts — use tokens from src/styles/theme.css
  • Use Tailwind token classes directly — NEVER [var(--token)] when the token exists in @theme (e.g. text-brand-light, rounded-pill, bg-red-tint-subtle)
  • var() is FORBIDDEN in component source files (src/components/**/*.ts, src/components/**/*.tsx)
  • If a token or mixed visual treatment does not exist, define it centrally in src/styles/theme.css or src/styles/base.css as a reusable token-backed utility/class, then consume that class from the component
  • If a token does not exist for a value, CREATE it in theme.css first — never use raw rgba(), hex, or px values inline
  • var() is only acceptable inside the style system (src/styles/theme.css, src/styles/base.css) to define reusable utilities such as bg-gradient-*, shadow-glow-*, or semantic component helper classes
  • Token reference: docs/DESIGN.md — read it before building any component
  • Never modify theme.css without explicit user confirmation
  • Never add dependencies without explicit user confirmation
  • Repo package manager contract is pnpm@10.34.1; when docs, scripts, or workflows pin pnpm, use the exact version, not only 10
  • For package-facing changes (package output, exports, generated declarations, peer ranges, React major upgrades, or CI/package distribution policy), require pnpm run build; require pnpm run verify:package when published output or consumer compatibility can change. Tests/Storybook alone are not enough for React major upgrades.
  • Generated declarations must not leak internal path aliases or CSS side-effect imports into the published .d.ts output
  • English only — code, comments, stories
  • Paired repository docs are bilingual: base *.md files are Spanish and matching *.en.md files are English. When editing docs under docs/ or root README files, preserve that split, update both language variants when the content changes, and never replace the Spanish base file with English prose.
  • Commit messages must follow the commitlint-enforced Conventional Commit format: <type>(<optional scope>): <description>. PR titles should follow the same format for review consistency. Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test. Use scopes for domains such as a11y, tokens, or infra instead of inventing custom types.

Skills

Load the relevant skill for detailed workflows:

Trigger Skill
Contributor shares a GitHub issue URL or component spec and asks to implement it component-contributor
User provides a HeroUI/reference component and wants an implementation-ready spec before coding component-spec-proposer
Reviewing an existing component — code quality, visual states, tokens, accessibility components-auditor
Auditing the design system package — token architecture, folder structure, npm distributable standards system-auditor
External project wants to use Stack-and-Flow as a base and customize its tokens bootstrapping
Contributor asks if their PR is ready for review, or agent must validate implementation before handoff, including package evidence when package-facing changes exist pr-reviewer
Creating or auditing GitHub Project board tasks — issues, fields, phases, team assignments github-project-tasks
Creating a release, bumping versions, generating changelogs, publishing to npm release-changeset
Preparing or auditing package distribution policy — exports map, package.json hygiene, package verification, consumer compatibility, TypeScript declarations npm-architect
Visual review — component states, glow, transitions, focus rings, contrast, accessibility visuals visual-review
Creating git worktrees or isolated writer checkouts for this repo worktree-location