Skip to content
HAv5.0
Docs

Writing

Notes from building design systems and the products on top of them. Newest first, all on one page.

  1. 2026

  2. I kept telling AI the same things every session. So I started writing them down as skills, and testing them like code.

    AITools2 min

  3. Component docs used to be written for people. Now agents build screens from them, and take every word literally. So I rewrote ours as rules.

    SystemsAI2 min

    Most component docs say something like “use the primary button for the main action and keep it prominent.” A designer reads that and fills the gaps from experience.

    An agent can’t though. It guesses. What counts as the main action? How prominent is prominent? Can a page have two? Each guess is a small drift from the system.. and when an agent is building whole screens, that drift adds up fast.

    Before: prose

    ## Button / PrimaryUse for the main action on a page. Keep it prominentand avoid overusing it. Pair with a secondary buttonwhere needed.

    Nothing in that paragraph is wrong, not so? It just can’t be checked.

    After: rules

    component: Buttonvariant: primaryuse_when: the single main action in a viewmax_per_view: 1pairs_with: [Button/secondary]never_for: [destructive actions, navigation]tokens:  bg: action.bg  label: action.label

    Every adjective became something a machine can hold to. “Prominent” became a token. “Avoid overusing it” became a limit of one per view. “Where needed” became an explicit pairing. Same intent. Nothing left to guess.

    Why it works

    1. A rule can be checked. An adjective can’t. So a one-off manual audit becomes one you can repeat.
    2. People benefit too. New designers stop asking what “prominent” means.
    3. The prose doesn’t disappear though. It moves to the why, where judgment belongs.

    I think that’s the real shift. Docs aren’t only for people any more.

    Examples are illustrative. They show the shape of the change, not ecoPortal’s actual docs.