> ## Documentation Index > Fetch the complete documentation index at: https://docs.openboa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Design Canon # Design Canon This page is the stable design canon for autonomous project work in this repository. Workers should use this page to judge whether a UI change feels aligned before moving a PR toward final signoff. ## Implementation model Build the UI in three layers. 1. shared primitives * base buttons, badges, inputs, textareas, avatars, separators, and sidebars * these should come from the adopted primitive system and be tuned through tokens and variants 2. composed patterns * repeated application patterns such as row layouts, meta pills, count badges, pane headers, and composers * these should be built by composing shared primitives, not by bypassing them with one-off markup 3. surface assembly * chat, work, observe, and future product surfaces * these should assemble composed patterns instead of inventing a new local visual language When a defect repeats in more than one place, fix the primitive or composed pattern first. ## Taste summary The product should feel calm, durable, businesslike, and high-signal. It should not feel decorative, playful, or overloaded. ## Foundation-first rule Before polishing a surface, stabilize the shared UI rules that the surface depends on. * fix repeated alignment, sizing, radius, and meta-placement problems in shared primitives before applying one-off surface tweaks * prefer stable row structures such as `left / content / right` over absolute overlays for badges, counts, and status * use surface-specific overrides only after the primitive or reusable pattern is already believable * treat recurring micro-defects across multiple components as a design-system problem first, not a local patch problem * do not consider a surface polished if its clean appearance depends on ad hoc exceptions instead of consistent primitives ## Interaction principles * prioritize clarity over cleverness * prioritize continuity over novelty * prefer familiar productivity patterns over custom metaphors * make important state obvious without increasing noise ## Density and layout rules * default to compact, readable density * prefer continuous lists and dividers over unnecessary boxes * keep section padding small unless spacing is doing real structural work * create larger gaps between true sections, not between related rows ## Token families The design system should stay small and predictable. * radius * use a narrow radius scale for controls, rows, and panels * avoid introducing new corner styles for one surface * spacing * use a compact spacing ladder and reuse it across headers, rows, and composers * repeated micro-adjustments should be promoted into shared spacing rules * control sizing * use one shared control height scale for badges, icon buttons, fields, and pills * avoid one-off heights unless a component is truly exceptional * typography * use one display family, one UI/body family, and one mono family * metadata should rely on quieter size and tone, not custom fonts per surface * color * default to neutral surfaces and restrained emphasis * reserve accent and workflow color for real state, not decoration * elevation * prefer borders and subtle contrast before stronger shadows * use stronger depth only for true shell boundaries, not routine list items ## Typography and hierarchy rules * hierarchy should come from size, weight, and spacing before color * metadata should be quieter than primary content * labels should be short, stable, and easy to scan ## Color and emphasis rules * default surfaces should stay restrained and mostly neutral * use emphasis only where it changes understanding, priority, or state * avoid spreading accent color across large surfaces when a compact signal is enough ## List vs card discipline * navigation rows should read as lists, not independent cards * transcripts and thread replies should read as continuous conversation, not dashboard tiles * use cards only for true major containers or detail panels with a distinct semantic boundary ## Surface construction rules * major containers may define the shell, but most interactive detail should live in rows, dividers, and restrained controls * headers should communicate one dominant idea quickly; avoid stacking explanatory chrome when one line and one secondary detail will do * composer bars, thread rows, and navigation items should feel like parts of one system, not like unrelated custom widgets * if a UI issue repeats across header, list, thread, and composer, solve the shared pattern before the local surface ## Canonical composed patterns These patterns should be stabilized before surface-specific polish. * pane header * eyebrow, title, description, and actions should come from one repeated structure * use it for sidebars, transcript headers, thread panes, and future work/detail panes * list row * default anatomy is `left / content / right` * counts and status belong in trailing meta, not in absolute overlays * meta pill * pills carry compact state or counts and should stay visually restrained * prefer them for room counts, participants, mentions, or compact status * composer shell * editor, toolbar, and primary action should read as one control family, not as separate widgets * message row * transcript and thread should share the same author/meta/body rhythm unless a clear scope reason demands density changes ## Shaping principles for a good system * prefer a primitive that teams will actually reuse over a theoretically perfect abstraction that they will bypass * choose flat APIs for simple, repeated usage and composed patterns for complex or extensible usage * design the system so common product needs fit naturally without local hacks * treat the design system as a product that must remain easy to adopt, not as a static style guide ## What counts as visually unacceptable * noisy emphasis * excessive empty space that weakens scanning * stacked boxes with no semantic reason * inconsistent alignment or badge positioning * a surface that reads more like a dashboard than a believable coordination tool