| name | component-development-workflow |
| description | Step-by-step workflow for creating components in Sando Design System. Ensures no deliverable is forgotten: structure, tokens, logic, tests, stories, changelog, and verification. Each step references specific guidelines for the agent to consult.
<example> User: "Create a Card component" Assistant: "I'll follow the component-development-workflow to create sando-card with all deliverables." </example>
<example> User: "Build a new Tooltip component" Assistant: "Using component-development-workflow to ensure structure, tokens, tests, stories, and changelog are all completed." </example> |
| license | MIT |
| metadata | {"category":"development","version":"1.0.0","author":"Sando Design System Team","tags":["web-components","lit","workflow","components","checklist"]} |
Component Development Workflow
Purpose
Guide agents through a complete component creation workflow ensuring all deliverables are produced. This is a high-level checklist—implementation details are decided by the agent per component.
When to Use
- Creating a new component from scratch
- Ensuring no deliverable is missed (tests, stories, changelog, etc.)
- Need a structured workflow to follow step-by-step
Workflow Steps
Step 1: 📁 Create Component Structure
Objective: Scaffold the component directory and base files.
Actions:
- Create component directory in
packages/components/src/components/{name}/
- Generate base files following the 7-file pattern
- Ensure proper naming conventions (
sando-{name})
Consult Guidelines:
| Guideline | Path | Purpose |
|---|
| Component Architecture | .opencode/guidelines/02-architecture/COMPONENT_ARCHITECTURE.toon | 7-file pattern, structure |
| Monorepo Structure | .opencode/guidelines/02-architecture/MONOREPO_STRUCTURE.toon | Package organization |
| Naming Conventions | .opencode/guidelines/03-development/NAMING_CONVENTIONS.toon | File and class naming |
Step 2: 🎨 Create/Verify Tokens
Objective: Ensure Recipe tokens exist for the component.
Actions:
- Check if component needs Recipe tokens
- Create tokens in
packages/tokens/src/recipes/{name}/
- Verify tokens build correctly with Style Dictionary
Consult Guidelines:
| Guideline | Path | Purpose |
|---|
| Token Architecture | .opencode/guidelines/01-design-system/TOKEN_ARCHITECTURE.toon | 3-layer system |
| Token Build System | .opencode/guidelines/02-architecture/TOKEN_BUILD_SYSTEM.toon | Style Dictionary config |
| Theming Strategy | .opencode/guidelines/01-design-system/THEMING_STRATEGY.toon | Flavor system |
Contextual Guidelines (if applicable):
| Context | Guideline |
|---|
| Uses colors | 01-design-system/COLOR_SYSTEM.toon |
| Uses typography | 01-design-system/TYPOGRAPHY_SYSTEM.toon |
| Uses spacing | 01-design-system/SPACING_SYSTEM.toon |
Step 3: ⚙️ Implement Component Logic
Objective: Write the component's TypeScript/Lit code.
Actions:
- Implement component class with
FlavorableMixin
- Add properties, events, slots as needed
- Implement keyboard navigation if interactive
- Apply styles using Recipe tokens
Consult Guidelines:
| Guideline | Path | Purpose |
|---|
| Code Style | .opencode/guidelines/03-development/CODE_STYLE.toon | TypeScript standards |
| Component Design | .opencode/guidelines/01-design-system/COMPONENT_DESIGN.toon | UX patterns |
| Keyboard Navigation | .opencode/guidelines/04-accessibility/KEYBOARD_NAVIGATION.toon | A11y interactions |
Contextual Guidelines (if applicable):
| Context | Guideline |
|---|
| Has animations | 01-design-system/MOTION_DESIGN.toon |
| Has loading states | 01-design-system/LOADING_STATES.toon |
| Uses screen reader | 04-accessibility/SCREEN_READER_SUPPORT.toon |
Step 4: 🧪 Create Tests
Objective: Write unit tests and accessibility tests.
Actions:
- Create
sando-{name}.test.ts with unit tests
- Create
sando-{name}.a11y.test.ts with accessibility tests
- Ensure coverage meets minimum threshold (≥80%)
- Run tests to verify they pass
Consult Guidelines:
| Guideline | Path | Purpose |
|---|
| Testing Strategy | .opencode/guidelines/03-development/TESTING_STRATEGY.toon | Test patterns |
| Test Coverage | .opencode/guidelines/05-quality/TEST_COVERAGE.toon | Coverage requirements |
| WCAG Compliance | .opencode/guidelines/04-accessibility/WCAG_COMPLIANCE.toon | A11y requirements |
Contextual Guidelines (if applicable):
| Context | Guideline |
|---|
| Color contrast tests | 04-accessibility/COLOR_CONTRAST.toon |
Step 5: 📖 Create Storybook Stories
Objective: Document component in Storybook with interactive examples.
Actions:
- Create
sando-{name}.stories.ts
- Add stories for all variants and states
- Configure argTypes for controls
- Add accessibility addon checks
Consult Guidelines:
| Guideline | Path | Purpose |
|---|
| Storybook Stories | .opencode/guidelines/06-documentation/STORYBOOK_STORIES.toon | Story patterns, CSF 3.0 |
Step 6: 📝 Update CHANGELOG
Objective: Document the new component in the changelog.
Actions:
- Add entry to
CHANGELOG.md under "Unreleased" or current version
- Follow conventional changelog format
- Include component name, brief description, and any breaking changes
Consult Guidelines:
| Guideline | Path | Purpose |
|---|
| Git Workflow | .opencode/guidelines/03-development/GIT_WORKFLOW.toon | Commit and changelog format |
Step 7: ✅ Verify Integration
Objective: Ensure component is properly exported and integrated.
Actions:
- Export component from
packages/components/src/index.ts
- Verify TypeScript types are exported
- Run full test suite:
pnpm test
- Run Storybook build:
pnpm docs:build
- Verify no linting errors:
pnpm lint
Consult Guidelines:
| Guideline | Path | Purpose |
|---|
| Monorepo Structure | .opencode/guidelines/02-architecture/MONOREPO_STRUCTURE.toon | Export patterns |
| Test Coverage | .opencode/guidelines/05-quality/TEST_COVERAGE.toon | Quality gates |
Completion Checklist
Before marking the component as complete:
Anti-Patterns
| ❌ Don't | ✅ Do |
|---|
| Skip steps because "it's simple" | Follow all steps regardless of complexity |
| Forget to update CHANGELOG | Always update CHANGELOG as final step |
| Create stories without all variants | Include all variants and states |
| Skip accessibility tests | A11y tests are mandatory |
| Hardcode values instead of tokens | Always use Recipe tokens for styling |
Example Usage
Agent receives: "Create a Card component"
Agent follows workflow:
- 📁 Creates
packages/components/src/components/card/
- 🎨 Creates tokens in
packages/tokens/src/recipes/card/
- ⚙️ Implements
sando-card.ts with slots and variants
- 🧪 Creates
sando-card.test.ts and sando-card.a11y.test.ts
- 📖 Creates
sando-card.stories.ts with all variants
- 📝 Updates
CHANGELOG.md with new component entry
- ✅ Exports from index, runs tests, verifies build
Version: 1.0.0
Author: Sando Design System Team
