story-writing

Guides writing Storybook stories for design-system components with canonical structure and quality rules.

5|9|Updated Mar 25, 2026
One-click install
npx skills add https://github.com/ajenchen/design-system --skill story-writing-ajenchen
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: story-writing
Source: https://github.com/ajenchen/design-system/tree/main/.agents/skills/story-writing
Command: npx skills add https://github.com/ajenchen/design-system --skill story-writing-ajenchen

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing Storybook stories for a design system often produces inconsistent examples, placeholder content, and drift between component code, specs, and stories. This Skill enforces a canonical workflow so every .stories.tsx, .principles.stories.tsx, and .anatomy.stories.tsx file uses real product scenarios, consistent structure, and stays synchronized with the component's code and spec. ## Core Features & Use Cases - Three-layer story positioning: Routes each story to the correct layer — showcase (visual catalog), anatomy (technical spec replacing Figma inspect), or principles (usage judgment with do/don't examples). - Registry-driven baselines: Loads a story-baseline registry per primitive component, copies production-grade canonical patterns, and blocks writing stories without a registry entry. - Anatomy 6-story standard: Enforces the canonical Overview, Inspector, ColorMatrix, SizeMatrix, StateBehavior, and Accessibility exports with token-first values cross-checked against the component's cva definitions. - Use Case: When asked to add stories for a Button component, the Skill reads the spec and cva definitions, maps spec rules to stories via trait-based templates, selects real SaaS scenarios (Jira, Stripe, Notion), and runs a self-check checklist before delivery. ## Quick Start Ask the assistant to write or review stories for a design-system component, for example by saying "write anatomy stories for the Button component".

Frequently Asked Questions about story-writing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write Storybook stories for a design-system component?

Read the component's spec.md and cva definitions first, then load the story-baseline registry for canonical patterns. Map spec rules to stories using trait-based templates, choose real SaaS scenarios, and run the self-check checklist before delivery.

What is the difference between showcase, anatomy, and principles stories?

Showcase stories (.stories.tsx) are a visual catalog of variants and states. Anatomy stories (.anatomy.stories.tsx) are technical specs replacing Figma inspect with token and size matrices. Principles stories (.principles.stories.tsx) teach when to use which variant with do/don't examples.

What stories must an anatomy file contain?

Every anatomy file must contain six canonical exports: Overview, Inspector, ColorMatrix, SizeMatrix, StateBehavior, and Accessibility, with mandatory Chinese name overrides. Skipping a section requires a written rationale in the component's spec.md or an @anatomy-rationale header comment.

Can I use placeholder content like Option A or Lorem ipsum in stories?

No. Placeholder text, abstract codenames, extreme unrealistic cases, and ASCII-art expressions are explicitly banned. Examples must come from real SaaS products like Jira, Stripe, or Notion, or common business flows, and must pass the 5-second comprehension and generalization tests.

How do I keep stories in sync when component code changes?

When the .tsx or .spec.md changes, grep the component's files for default markers and update all three layers together. The cva defaultVariants field is the highest-risk drift point, so update the spec, docblock, and anatomy SIZE_SPECS in one pass.