Reference · Design notes

Design notes

The hidden invariants of the design system - so the next agent doesn't undo them. A small set of design decisions that look weird if you don't know the why, captured here so an unfamiliar contributor (human or AI) reads the reasoning before “cleaning” them up. Starts with the “HTML-only reflection” rule for brain index files.

See it in motion

Where to find it

  • Desktop: http://localhost:4000/, then Reference (drawer) → Design notes in the sidebar.
  • Hosted: repoops.ai/team/reference (browse it from the Reference drawer)
  • Keyboard: ⌘ K, then type “Design notes”.
  • On disk: .claude/brain/design-lessons-html-over-markdown.html

What it does for you

Stops the next refactor from undoing this one.Every entry pairs the rule with the original reasoning + the failure mode that motivated it. Read once at session start; never re-litigate the same decision.
HTML-only reflection - why brain index files are HTML, not markdown.Some brain index files (the architecture map, the canonical-tab manifest) carry richer affordances - sortable tables, interactive filters, family trees - that markdown can't express. Those stay HTML, with no .md source. Trying to “normalize” them to markdown loses the affordance and the reasoning.
Lives next to the design system, on purpose.The design tab covers tokens, type, motion, light + dark. Design notes covers the meta-rules - the “why isn't this consistent with X” questions an unfamiliar contributor would otherwise resolve by refactoring.

Configure

Nothing - it's a hand-curated HTML file. New design lessons get appended as a section with the same shape: Rule · Reason · Failure mode.

Use it well

Open Design notes before any “normalize” / “clean up” / “why isn't this in markdown” PR. If the thing you're about to change has a Design note, the note is the answer; if it doesn't, add one when you make the change so the next agent inherits the reasoning.

Read more