One column of meaning
Content flows top-to-bottom in a clear reading order. Side rails are for navigation and metadata, never the primary message.
B-DNA
Brand Design DNA · UI/UX Guideline System
Source of truth → Branding Guideline
Brand Design DNA · Guideline Layer
A branding guideline system, not a theme.
B-DNA defines how UI/UX decisions stay consistent across the product — a documentation layer covering structure, color usage, typography, components, spacing, motion and hierarchy. It borrows the discipline of Bolt's brand thinking (color earns attention; neutral does the work), yet it ships no styles: it changes no theme tokens and overrides no existing UI. Read it before you build, audit against it before you ship.
Reference: Bolt brand · companion to S-DNA and the Branding Guideline.
1source of truth — the existing
--c-* tokens0token or color overrides — guideline only
8rule domains, one consistency gate
UI structure rules
A page is a stack of clearly bounded sections built from a single primitive: the card. Structure first, decoration never.
Cards before tables
Group related data in cards. Reach for a table only for dense, comparable rows — never as the default container.
Bounded sections
Every section has a kicker, a title and a one-line purpose. If a block can't be named, it doesn't belong.
Flat z-index
Surfaces sit at one elevation. Overlays (menus, dialogs) are the only thing allowed to float above content.
- Keep a predictable container width and consistent section rhythm.
- Lead each section with intent, then detail.
- Use surfaces (
--c-bg-surface) to separate, not heavy borders.
Do
- Nest cards inside cards inside cards.
- Mix three competing layouts on one screen.
- Restyle global navigation, header or footer from a feature page.
Don't
Color usage rules
Bolt-inspired logic, applied to our palette: color earns attention, so spend it deliberately. These are usage rules only — every swatch below is an existing theme token. No new color is introduced and no token is changed.
Three roles
Primary marks the one action you want taken. Action is reserved for high-stakes or destructive moments. Neutral carries everything else — and it is roughly 90% of any screen.
The 90 / 10 budget
Neutral surfaces and text dominate; primary and action are the exceptions that direct the eye. If color is everywhere, it points to nothing.
- Spend primary on the single most important action per view.
- Read color from
var(--c-*)so light/dark just works. - Let neutral and whitespace create calm.
Do
- Hard-code hex values or invent a new palette.
- Fill large areas with primary or action color.
- Adopt Bolt's actual green — borrow the discipline, not the hue.
Don't
Typography system rules
One family, inherited from the site. Hierarchy comes from size and weight — not from new fonts or color. Samples below render in the live theme font.
Display
Heading 1
Heading 2
Heading 3 — section label
Body — the default reading size for prose and descriptions.
Caption · meta · label
code / token / value
- Build hierarchy with weight and scale, not new typefaces.
- Keep prose measure to ~60–75 characters.
- Use tabular numerals for data and metrics.
Do
- Introduce a decorative or display font.
- Use color as the only signal of hierarchy.
- Center long paragraphs or stretch lines edge-to-edge.
Don't
Component rules
Buttons, cards and inputs are the core kit. Reuse them before inventing anything. Each demo below is scoped to this page and built only from theme tokens.
Buttons
One primary per view. Secondary and ghost carry lower-priority actions; danger is reserved for destructive intent.
Cards
The default container: soft surface, thin border, generous padding, ~14px radius.
Default primitive
Group related content here before reaching for any other layout. Hover shows the standard lift.
Inputs
Always paired with a label and an optional helper. Focus uses the theme focus ring for accessibility.
Helper text sits below, muted and small.
Native control, themed border + focus.
- Extend an existing component before creating a new one.
- Give every interactive element a visible focus state.
- Keep one clear primary action per surface.
Do
- Ship inputs without labels or helper context.
- Stack multiple primary buttons competing for attention.
- Override global component styles from a single page.
Don't
Layout & spacing rules
All spacing steps off a 4px base. Whitespace is a feature, not leftover room — when in doubt, add space, not another element.
- Pick gaps and padding from the 4px scale only.
- Keep a consistent vertical rhythm between sections.
- Use one radius family (~10–14px) across surfaces.
Do
- Use arbitrary one-off values like 7px or 23px.
- Compress dense data to remove breathing room.
- Mix sharp and round corners in the same group.
Don't
Interaction & motion rules
Motion clarifies state; it never performs. Transitions land in 150–250ms with subtle easing, and always respect reduced-motion.
Lift, don't leap
A 3px rise and a soft shadow at 200ms. Enough to feel responsive, never enough to distract.
State changes are felt, not announced.
- Keep durations in the 150–250ms range.
- Animate to communicate state and continuity.
- Honor
prefers-reduced-motioneverywhere.
Do
- Use bounce, spin or large scale transforms.
- Animate purely for decoration.
- Block interaction while an animation plays.
Don't
Information hierarchy rules
Make the important thing obvious in one glance. Large numbers earn weight; labels support; units whisper.
Monthly active
128,400 users
The value dominates, the label orients, the unit recedes — the same pattern scales to any metric.
- Keep exactly one H1 and a scannable heading order.
- Give key metrics the most visual weight.
- Reveal detail progressively — summary first.
Do
- Make everything bold — then nothing reads as important.
- Bury the primary message below secondary noise.
- Skip heading levels for visual effect.
Don't
Consistency checker
Before shipping any new UI, walk this checklist. The readiness meter updates live — aim for 100% and pass the gate question.
0%
Needs work — does not meet the B-DNA bar yet.
Gate question: “Would this look like it has always belonged in the product?” If not — simplify.