Documentation practices

Lesson learned

Move the source of truth as the team matures

Many design systems begin with detailed component specifications in Figma. At the outset, that can be a sensible contract: designers describe anatomy, variants, states and tokens, then engineers translate the specification into production components.

The working relationship changed the documentation model. Designers gained access to VS Code and GitHub, began with small token changes and, as their capability and AI tooling improved, contributed more substantial component and documentation changes. The separate Figma specification eventually became stale because the production decisions were happening elsewhere.

1. 01
   Specify in Figma

   Detailed component specifications give engineering a clear starting contract.

2. 02
   Implement together

   Design and engineering resolve behaviour, tokens and exceptions collaboratively.

3. 03
   Contribute in the repository

   Designers make reviewed changes to tokens, components and guidance alongside engineers.

4. 04
   Publish from Storybook

   Executable examples and guidance live beside the code that consumers install.

5. 05
   Expose a machine-readable contract

   Structured intent helps AI tools inspect, generate and validate without guessing.

The living source

Put component guidance beside the component

Figma remains valuable for visual exploration, composition and design review. It should not duplicate a complete component manual if the team cannot keep that manual synchronised with production.

Storybook can become the practical source when the main audience is engineers. Its MDX pages combine written guidance with live examples, Figma references, accessibility guidance and changelogs. Adjacent stories define controls, variants and interaction tests. This makes the documentation inspectable and testable instead of a static handoff artefact.

Component standard

Use one repeatable page contract

A component page should answer design and implementation questions in a predictable order. Nathan Curtis describes strong component documentation as content architecture for several audiences, not merely a generated property table. Storybook Autodocs is a useful baseline; the human guidance is what turns it into a design-system page.

Use progressive disclosure for different readers. Product owners, product managers and business analysts need the purpose and constraints quickly. Designers need anatomy and composition. Engineers need executable examples, APIs and dependency notes. One canonical page can serve all of them without giving every audience the same level of detail at once.

Library-first implementation

Document the decisions the system adds

Do not rebuild every control from first principles when an established framework already provides dependable behaviour. For icare, the practical starting point is its existing Bootstrap implementations: document the supported versions, apply shared tokens and styling contracts, and be explicit about what the design system adds or overrides.

iCare largely uses Bootstrap, with different Bootstrap versions maintained across different products and codebases. Documentation must therefore identify the product and Bootstrap version an example applies to. It should distinguish the common iCare design decision from the version-specific markup, utilities and behaviour used to implement it.

Each page should explain what comes from Bootstrap, what iCare has mapped or overridden, and where a product implementation intentionally differs. Consumers should never have to reverse-engineer whether a behaviour belongs to Bootstrap, the design system or the product.

The intermediate layer

Describe intent in a tool-neutral form

Figma data describes how Figma stores a design. Framework code describes how one implementation renders it. Neither is a neutral description of what the component means. The Missing Language of User Interfaces makes the case for an intermediate representation: structured enough for software to parse, but readable enough for a designer and engineer to review together.

YAML can be a convenient authoring format, but YAML itself is not the goal. The goal is a stable schema for intent: component anatomy, relationships, variants, states, token roles, accessibility expectations and implementation mappings. Tokens should use the established Design Tokens Community Group JSON format for exchange; a component specification can reference those tokens without inventing another colour system.

The article uses Layla, a compact layout language, to explore this approach. It is a useful prototype rather than an established standard. Its most transferable lesson is the workflow: translate design into a reviewable intermediate form, have a human verify the intent, then let AI or deterministic tools generate platform-specific output.

component: icare-button
intent: Trigger an immediate action
anatomy:
  - leadingIcon: optional
  - label: required
variants: [primary, secondary, tertiary]
states: [default, hover, focus, disabled, loading]
tokens:
  background: "{colour.background.interactive}"
  label: "{colour.text.on-interactive}"
accessibility:
  element: button
  keyboard: [Enter, Space]
implementation:
  base: Bootstrap
  versionPolicy: product-owned
  systemClass: icare-button

AI-assisted practice

Let AI accelerate contribution, not invent the rules

AI can lower the barrier for designers to work in the repository, generate first-pass stories and translate a reviewed contract across frameworks. It also amplifies ambiguity. A machine-readable document that omits relationships or intent is still an incomplete specification.

1. 1Capture intent

   Agree the design decision and structured component contract.

2. 2Human review

   Designer and engineer resolve semantics, dependencies and exceptions.

3. 3Generate

   Use AI for stories, prose, mappings and framework-specific scaffolding.

4. 4Verify

   Run interaction, accessibility, token and visual tests.

5. 5Publish together

   Merge code, stories, guidance and changelog in one reviewed change.

The documentation is not a second product beside the system. It is the human-readable and machine-readable surface of the system itself.

Start at iCare

Make the next version deliberately small

• Agree a Storybook page template and apply it to one high-use component.
• Mark old Figma component specifications as archived rather than maintained guidance.
• Inventory the Bootstrap version used by each product and publish a maintained compatibility matrix.
• Record Bootstrap dependencies, iCare overrides and version-specific implementation notes on each component page.
• Publish tokens in the Design Tokens Community Group format and reference them from component documentation.
• Pilot one reviewed, machine-readable component contract before designing a schema for the whole library.
• Require documentation, tests and changelog updates in the same pull request as a component change.