BDG is how we keep everything Brainfish makes, from a quick prototype to production code, feeling like one product. It has three parts that always agree with each other, because they are built from the same source:

• Tokens: the named values (colours, spacing, type, shadows, motion). Exported from Figma, built into CSS and Tailwind.
• Guidelines: what to use, when, and why. Markdown in guidelines/, rendered as this site.
• Skill: the guidelines packaged as agent skills for any AI model or tool, so "build me a settings page" comes out on-brand the first time.

Learn it in 10 minutes

Read these in order. Each page starts with a summary, so skim and come back for detail.

1. Principles and Taste: the ideas behind every decision, and the small details that make UI feel right. (3 min)
2. Semantic colour, Palette and Theming: the tokens you build with, the raw ramps behind them, the two themes (BF and Ballet), dark mode. (3 min)
3. Typography and Spacing: Fraunces for display, Geist for everything else, an 8px grid named like Figma. (2 min)
4. Button: the signature "stamp" control. If you understand this one you understand the look. (1 min)
5. App shell: where everything sits on screen. (2 min)
6. Motion: when to animate at all, then which curve and duration. (2 min)

Use the theme and mode switches in the site header while you read: every example on every page is live.

The mental model

primitive     →  semantic             →  component         →  layout
--bf-lime-400    --bf-brand              .bf-btn--primary     .bf-app
--bf-mono-700    --bf-text-subtle        .bf-nav-item         list-detail page
--bf-space-100   (gap inside a button)   .bf-input            empty state

• You almost never touch primitives. They are the palette.
• You build with semantic tokens. They say what a value is for, and they change with theme and mode.
• Components and layouts are recipes made of semantic tokens. Use them before inventing anything new.

Use it every day

Install

In a product repo (Tailwind v3):

// tailwind.config.js
module.exports = {
  presets: [require('./vendor/bdg/dist/tailwind-preset.cjs')],
  content: ['./src/**/*.{ts,tsx}'],
};

/* global.css */
@import './vendor/bdg/dist/tokens.css';

<html data-theme="bf" data-mode="light">

Tailwind v4: @import "tailwindcss"; @import "./tokens.css"; @import "./tailwind-theme.css";

For a prototype or artifact (no build step): link dist/tokens.css and dist/bdg.css, add class="bf-root" to <body>, and use the .bf-* classes shown on every component page.

For AI agents: install the brainfish-design skill (see skills/brainfish-design). Agents that read .agents/skills/ pick it up automatically inside this repo; see Agent skills for other tools.

1. Calm canvas, sharp actions

The product is mostly white surface on a cream app background, set in neutral mono. Colour is rare, and that rarity is what makes it useful. brand marks the one primary action on screen and where you are in the navigation. If everything is lime (or purple), nothing is.

2. Tactile, not glossy

Controls look physical. Buttons have a hard 2px "stamp" shadow that lifts on hover and presses in on click. There are no gradients on controls, no glassmorphism and no soft glows on buttons. Softness is for surfaces: the main canvas floats on shadow-app, while controls stay crisp.

3. Editorial voice, product precision

Fraunces (a serif) appears only at the largest sizes: page titles, empty-state headlines, h1 and h2. Everything you read or operate (body, labels, data) is Geist. Numbers that matter use Geist Mono.

4. AI is a material, not a mascot

The yellowfin gradient (blue to green to lime) means "AI is here": the Ask Brainfish prompt and the Generated by Brainfish AI badge. The AI loader is the Brainfish ripple, in the text colour. Never use it for decoration, and never use it for non-AI things.

5. One source, many outputs

A value exists once, as a token. Figma, code, prototypes and AI agents all read it. If you're typing a hex code, a pixel value or a duration, stop: either the token exists, or it's missing and should be proposed.

Taste isn't a matter of preference. It's a trained instinct: seeing why one version feels better than another, and being able to say why. Almost every taste decision has a reason, and once it's written down, anyone (or any agent) can follow it. This page writes those reasons down. The brainfish-taste skill applies them to any UI you hand it.

Three beliefs

Unseen details compound. Most details are never consciously noticed, and that's the point. When something behaves exactly as people assume it should, they move on without a thought. A thousand small correct decisions add up to a product people love without knowing why.

Beauty is leverage. Our customers choose support tools on how the whole experience feels, not just a feature list. Good defaults and good motion set us apart, so treat polish as product work, not decoration.

Taste is trained. Study interfaces that feel great, take apart why, and practise. When something feels off, slow it down, look again tomorrow, and name the cause.

Rules of thumb

Motion

The full rules are on the Motion page. The ones people break most:

• Keyboard actions and 100+/day actions don't animate. ⌘K opens instantly.
• Things enter with a strong ease-out, never ease-in.
• Nothing appears from scale(0). Start at 0.95 with opacity.
• Menus grow out of their trigger. Modals stay centred.
• UI motion stays under 300ms. A fast spinner makes loading feel faster.
• Hover motion is for real pointers only. Touch fires hover on tap.
• Exit faster than you enter. Be slow where the user is deciding and fast where the system responds.

Typography

• Keep running text to about 65 characters per line (--bf-prose-width).
• Use font-variant-numeric: tabular-nums anywhere digits line up: tables, metrics, counters, prices. The metric styles already do.
• Use the single ellipsis character …, not three full stops, and truncate with CSS (text-overflow: ellipsis) so it adapts to the container.
• Give uppercase labels a little letter-spacing (metric-label uses 0.04em). Never letter-space body text.
• Underlines are for links. Use weight or colour for other emphasis.
• Use bold (600) for emphasis in the interface and italics for citations and stress in prose.
• Choose fallback fonts that match the x-height and weight of Geist and Fraunces, so the page doesn't shift when fonts load.
• Balance headings and make prose pretty: text-wrap: balance and text-wrap: pretty.

Interaction

• Every pressable thing responds to a press. Buttons stamp; rows and cards change background.
• Small controls get a 44px hit area even when they look smaller (--bf-hit-area). .bf-btn--icon.bf-btn--sm already expands it.
• Once one tooltip is open, the next one opens instantly. The delay only protects the first.
• Handle edge cases invisibly. Pause a toast's timer while the tab is hidden, and keep hover state across the gaps between stacked items. Nobody notices, which is the point.
• Stress-test with worst-case data before calling something done: long names, empty lists, huge counts. The brainfish-break-ui skill does this.

Where Brainfish deliberately differs

A system needs its own point of view. These BDG choices knowingly differ from common "tasteful defaults", and each has a reason:

How to review for taste

Use a single table, one row per issue: what it is now, what it should be, and why. This is the format brainfish-taste and brainfish-review-motion use.

Rule of thumb: use semantic tokens (text-subtle, elevation-surface, brand) in code. Reach for a palette step (blue-100) only for things the semantic layer doesn't cover yet, such as data visualisation, avatars or stream colours, and say why in a comment.

How the layers work

Semantic tokens

Values below are for the default theme (bf, light). Switch theme or mode in the header to see them change.

Status, danger & disabled

What each group is for

• brand / on-brand: the primary action and the "you are here" marker (active nav icon, selected tree item bar, toggle on, checkbox on). It appears at most once per view as a filled button. on-brand is the text or icon colour that sits on it.
• accent: white in both themes and not used by any component yet, so don't build on it.
• text-default / subtle / subtlest: primary copy, secondary copy (descriptions, metadata), and tertiary copy (placeholders, timestamps, hints).
• text-link: inline links in prose. In the bf theme it is a dark lime (lime-700) so it stays readable on white.
• icon-default / icon-button: decorative and informational icons in grey, and icons inside controls in ink.
• border-button / input / subtle / subtlest / active: borders for stamp controls (ink), fields and dividers (light grey), stronger separators, hover borders, and focus or active borders.
• elevation-cream / surface / sunken: the app background behind everything, the main canvas, cards and menus, and wells, inset areas, ghost-button hover and code blocks.
• bg-hover / bg-selected / border-selected: hover fill for nav and controls, plus the selected fill and outline for nav items, menu items and option cards (a brand tint).
• status-*: pills and badges. Each has bg, fg and dot. See Status.
• danger-*: destructive buttons and confirmations.
• disabled-*: inactive controls.

Do and don't

• Do use one filled brand button per view. Everything else is secondary or ghost.
• Do pair every status colour with a text label. Colour is never the only signal.
• Don't put brand behind body text or use it as a section background.
• Don't use palette steps for text unless you've checked contrast (the contrast report runs on every build).
• Don't use the retired navy #244398, Satoshi or Inter. They still appear in older Figma components (see Figma fixes).

Code

.note { color: var(--bf-text-subtle); background: var(--bf-elevation-sunken); border: 1px solid var(--bf-border-input); }

<p className="text-subtle bg-sunken border border-input rounded-small p-150">…</p>

Don't build with these directly. The palette is what semantic colour tokens point at. Use a palette step only where the semantic layer has no token yet (data visualisation, avatars, stream colours) and say why in a comment.

Ramps

Nine hues plus mono. Mono and lime are mirrored in dark mode (step 100 becomes the darkest), so semantic tokens that point at them flip automatically.

Hue roles

Gradients

Gradients are material, not decoration. Yellowfin is the only gradient used in product UI and it means AI.

Do and don't

• Do check contrast before using a palette step for text (the contrast report runs on every build).
• Do use orange, teal and magenta only for data visualisation and stream colours.
• Don't hard-code a palette step where a semantic token exists (--bf-mono-700 for secondary text should be --bf-text-subtle).
• Don't use yellowfin, or any gradient, outside AI surfaces in product UI.

Code

/* chart series: no semantic token for data viz yet */
.series-1 { stroke: var(--bf-blue-600); }

Every semantic token has a value for each theme and mode. Components only reference semantic tokens, so switching is two attributes on the root element and nothing else changes:

<html data-theme="bf" data-mode="light">

Put data-theme and data-mode on the same element. You can scope a theme to part of a page (for example a preview card) by setting both attributes on that element.

What changes between themes

Only these semantic tokens differ between themes. Everything else is shared.

Dark mode

Dark mode follows the Foundations rule: "what's 700 in Light Mode would be 300 in Dark Mode."

• The mono and lime ramps are mirrored in the Figma export, so text-default (mono-900) becomes near-white automatically.
• elevation-surface becomes #000000, elevation-cream becomes #282828, and elevation-sunken becomes mono-100 (now #171717).
• The other hues (blue, green, red and so on) are not mirrored in Figma yet. BDG mirrors them for status and danger tokens only (marked derived).

Respect the user's OS preference unless they've chosen explicitly:

const mode = localStorage.getItem('bf-mode') ?? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
document.documentElement.dataset.mode = mode;

Contrast report

Generated on every build by npm run check. Failures are design decisions that belong in Figma, so they're tracked in Figma fixes rather than patched silently in code.

56 of 64 checked pairs pass. These don't:

<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400&family=Geist:wght@400;600&family=Geist+Mono:wght@400&display=swap" rel="stylesheet">

Scale

Every style is a single token: font: var(--bf-type-h3) sets weight, size, line height and family in one go. In Tailwind, use type-h3. In plain CSS for prototypes, use .bf-h3.

Usage

• One h1 per page. In the app it's the page title, for example Expansion plan in an article or Process refund in a workflow. Inside the app shell, page titles use h3 (Geist 600 24/28) because the canvas is dense. Reserve Fraunces h1 for empty states, onboarding and moments that should feel editorial.
• Body default is body-md (14/20). It's used in navigation, buttons, inputs and table cells. Use body-lg (16/24) for reading: article prose, the AI prompt and empty-state copy. Use body-sm (12/16) for metadata, timestamps, pills and tree items.
• Strong = 600, never 700. Use it sparingly for names in lists, labels and active nav.
• Metric label (10/14, uppercase) sits above a metric or marks a node type (TRIGGER, STEP 2 · LOOKUP).
• No italics for emphasis in headings. Never letter-space body text.
• Set text-wrap: balance on headings and text-wrap: pretty on prose. Limit prose to --bf-prose-width (65ch).

Code

<h1 className="type-h1 text-default">Meet your users where they are</h1>
<p className="type-body-md text-subtle">Add channels to deploy Brainfish inside your product.</p>
<span className="type-metric-label text-subtle">Resolution rate</span>

Token names are the step number from Figma, where 100 = 8px. Using the same names in code means a designer saying "spacing 150" and an engineer writing gap-150 mean the same 12px.

Which step when

Rules

• Use gap, not margins. Lay out with .bf-stack, .bf-inline or flex/grid gap (see Layout primitives).
• Padding is symmetric by default. Controls use 100 all round, and fields use 150.
• Don't invent steps. 10px, 20px and 14px don't exist. If the layout needs one, round to the nearest step, or propose a token if it recurs.

<div className="flex flex-col gap-300 p-300">…</div>   // Tailwind: same names as Figma

Nesting rule: an inner radius equals the outer radius minus the padding between them. If the result is 0 or negative, use small.

Borders

All borders are 1px. Exceptions: toggle, checkbox and radio use 1.5px, and focused fields add a 1px inset ring (2px total).

Surfaces

From back to front:

elevation-cream    the app background (with the lava-lamp wash in the shell)
elevation-surface  the main canvas, cards, menus, panels          + shadow-app when floating
elevation-sunken   wells inside a surface: code, card bodies, segmented-control tracks

Shadows

• shadow-app is for surfaces that float above the cream background: the main canvas, menus and popovers, the active segmented tab, and the AI prompt.
• shadow-raised is for cards that sit on a surface but need lift, such as workflow nodes and message bubbles.
• shadow-stamp-* is only for stamp controls: buttons, the edit button and icon buttons. It's a hard offset with no blur, in the control's border colour. Use 2px at rest, 3px on hover (with a −1px lift) and 1px when pressed (with a +1px push).

Don't put soft shadows on controls, and don't put stamp shadows on surfaces.

Library: Phosphor. Weight: Regular, with Fill for active and selected states where Figma shows it. No other icon sets.

Colour: icon-default (grey) for informational icons, icon-button (ink) inside controls, currentColor inside buttons so the icon follows the label.

Icons we use (from the Components file)

Navigation mapping (keep it consistent): Inbox = Tray, Knowledge = BookOpenText, Workflows = TreeStructure, Channels = ChatsTeardrop, Analytics = ChartPie, Help = Question.

Code

import { BookOpenText } from '@phosphor-icons/react';
<BookOpenText size={16} className="text-icon-button" aria-hidden />

<!-- prototypes: Phosphor web font -->
<script src="https://unpkg.com/@phosphor-icons/web@2.1.1"></script>
<i class="ph ph-book-open-text" aria-hidden="true"></i>

Rules

• Icon-only buttons need aria-label. Decorative icons get aria-hidden.
• Don't mix weights in one row of controls.
• Integration logos (Zendesk, Slack, Salesforce and 24 others) are full-colour brand marks from the data.external component set at 16 or 24px. Never recolour them.

Logo

The logo is monochrome and always embedded from file. Never redraw it, never set "Brainfish" in type as a stand-in, and never recolour the fish.

Minimum height: 16px. Clear space: the height of the fish on every side. In the app, the top-left slot holds the customer's org switcher (control.org), not our logo. Our mark appears in the Ask Brainfish button and in product chrome outside the app.

The Figma Brand page also has full / mark / text × default / black / color / white logo variants and favicons. Export them into assets/ as they're needed. Don't recreate them.

Byth (bathymetric contour)

A topographic contour pattern, used as a quiet watermark behind empty states and onboarding. You can see it on the Channels landing page, behind Meet your users where they are.

Meet your users where they are

• Use byth-light.svg on light surfaces and byth-dark.svg on dark ones. Keep it behind content at low contrast.
• Crop it with a circular or radial mask so it fades out. Never let it sit behind dense UI.

Lava lamp (app background)

app.bg.lavaLamp: two soft lime blobs on cream at the top-left and bottom-right corners of the app shell, under a 56px blur. It's what makes the shell feel like Brainfish without colouring any UI. Use the .bf-lavalamp element as the first child of .bf-app (see App shell). It isn't for cards, modals or marketing pages.

Files: dist/tokens.css (CSS variables), dist/tokens.json (resolved values per theme and mode), dist/tailwind-preset.cjs, dist/tailwind-theme.css.

Primitives are the smallest building blocks: a box that arranges its children with a token gap. Compose them instead of writing one-off flex CSS with margins.

<div class="bf-stack bf-gap-200" style="max-width:520px">
  <div class="bf-spread">
    <h3 class="bf-h4">Process refund</h3>
    <div class="bf-inline bf-gap-100">
      <button class="bf-btn bf-btn--secondary"><i class="ph ph-play-circle bf-icon"></i>Run</button>
      <button class="bf-btn bf-btn--primary"><i class="ph ph-check-circle bf-icon"></i>Save</button>
    </div>
  </div>
  <p class="bf-body-md bf-subtle">Stack (gap 200) containing a Spread, whose right side is an Inline (gap 100).</p>
  <div class="bf-grid" style="--min:140px">
    <div class="bf-card">One</div><div class="bf-card">Two</div><div class="bf-card">Three</div>
  </div>
</div>

Gap guidance

• Use 050–100 inside a control or between an icon and a label.
• Use 100–150 between controls in a toolbar, or between items in a list.
• Use 200–300 between groups and cards.
• Use 400 or more between page regions.

Surfaces

Pair a primitive with a surface class when it needs a background:

When to use

• Primary (brand fill) is the single most important action in the view: Save, Resolve, Send. Only one per view.
• Secondary (white) is every other action: Run, Discard, Edit, Create knowledge.
• Danger is for destructive actions that can't be undone. Always confirm.
• Ghost is for low-emphasis actions in dense UI: toolbars, card footers, "More".
• Icon is for square, icon-only actions (36×36). Requires aria-label.
• Split (Figma group) is a primary action with a dropdown of alternatives.

Don't use buttons for navigation between pages (use a link or nav item), and don't use them for filters (use a chip or control).

Anatomy

┌──────────────────────┐╮  border 1px border-button · radius small (4)
│ (icon 20)  Label     ││  height 36 · padding 8 · gap 4 · type body-md
└──────────────────────┘│  
 ╰──────────────────────╯  shadow-stamp-2 (hard, no blur)

Variants

<div class="bf-inline bf-gap-150">
  <button class="bf-btn bf-btn--primary"><i class="ph ph-check-circle bf-icon"></i>Resolve</button>
  <button class="bf-btn bf-btn--secondary"><i class="ph ph-pencil-simple bf-icon"></i>Edit</button>
  <button class="bf-btn bf-btn--danger"><i class="ph ph-trash bf-icon"></i>Delete</button>
  <button class="bf-btn bf-btn--ghost"><i class="ph ph-users bf-icon"></i>Co-author</button>
  <button class="bf-btn bf-btn--secondary bf-btn--icon" aria-label="Notifications"><i class="ph ph-bell bf-icon"></i></button>
  <span class="bf-btn-split">
    <button class="bf-btn bf-btn--primary"><i class="ph ph-paper-plane-tilt bf-icon"></i>Send</button>
    <button class="bf-btn bf-btn--primary" aria-label="More send options"><i class="ph ph-caret-down bf-icon" style="width:16px;height:16px"></i></button>
  </span>
</div>

States

<div class="bf-inline bf-gap-150">
  <button class="bf-btn bf-btn--primary" aria-busy="true"><span class="bf-spinner" style="width:16px;height:16px"></span>Saving</button>
  <button class="bf-btn bf-btn--primary" disabled>Save</button>
  <button class="bf-btn bf-btn--secondary bf-btn--sm"><i class="ph ph-plus bf-icon"></i>Small</button>
</div>

Tokens

brand, on-brand, elevation-surface, border-button, danger-*, disabled-*, radius-small, space-100, space-050, control-height, type-body-md, shadow-stamp-1/2/3, duration-instant, ease-out.

Code

Product (React + Tailwind):

const base = 'inline-flex items-center justify-center gap-050 h-[var(--bf-control-height)] p-100 rounded-small border type-body-md ' +
  'shadow-stamp-2 transition-[transform,box-shadow,background-color] duration-press ease-out ' +
  'hover-fine:-translate-x-px hover-fine:-translate-y-px hover-fine:shadow-stamp-3 active:translate-x-px active:translate-y-px active:shadow-stamp-1 ' +
  'disabled:bg-disabled-bg disabled:text-disabled-fg disabled:border-disabled-border disabled:shadow-stamp-1 disabled:translate-x-0 disabled:translate-y-0';

const variants = {
  primary: 'bg-brand text-on-brand border-button',
  secondary: 'bg-surface text-default border-button',
  danger: 'bg-danger-bg text-danger-fg border-danger-border [--bf-border-button:var(--bf-danger-shadow)]',
  ghost: 'bg-transparent border-transparent shadow-none hover-fine:shadow-none hover-fine:translate-x-0 hover-fine:translate-y-0 hover:bg-sunken',
};

export function Button({ variant = 'secondary', icon: Icon, children, ...props }) {
  return (
    <button className={`${base} ${variants[variant]}`} {...props}>
      {Icon && <Icon size={20} aria-hidden />}
      {children}
    </button>
  );
}

Prototype / artifact: <button class="bf-btn bf-btn--primary">.

Why the stamp and not scale(0.97)

The common press pattern scales a button to 0.97. BDG keeps the stamp instead, because it is the brand's signature: the button moves away from the pointer and the hard shadow shrinks, like a key going down. It follows the same rules as a scale press: 160ms, a strong ease-out, a transition (not keyframes) so rapid clicks retarget, and the hover half gated to real pointers. Under reduced motion the shift is dropped and only the shadow changes.

Accessibility

• Use a real <button>. Labels are verbs: Resolve, not OK.
• Icon-only buttons need aria-label. Split buttons need a separate label on the caret.
• Loading: set aria-busy="true" and keep the label (Saving), so screen readers know what's happening.
• Hit target ≥ 36×36 (already met by control-height).

Anatomy

Label                         type body-md-strong · text-default
┌─────────────────────────┐   height 44 · padding 12 · radius small
│ (icon 16) Placeholder   │   border 1px border-input · bg surface · type body-md
└─────────────────────────┘   placeholder text-subtlest
Helper or error text          type body-sm · text-subtlest / status-error-fg

<div class="bf-stack bf-gap-300" style="max-width:420px">
  <label class="bf-field">
    <span class="bf-label">Organisation name</span>
    <input class="bf-input" placeholder="Acme Inc.">
    <span class="bf-help">Shown to your customers in the help widget.</span>
  </label>
  <label class="bf-field">
    <span class="bf-label">Support email</span>
    <input class="bf-input" value="support@acme" aria-invalid="true">
    <span class="bf-help bf-help--error">Enter a full email address, like support@acme.com</span>
  </label>
  <label class="bf-field">
    <span class="bf-label">Default language</span>
    <select class="bf-select"><option>English (Australia)</option><option>English (US)</option></select>
  </label>
  <label class="bf-field">
    <span class="bf-label">Instructions</span>
    <textarea class="bf-textarea" placeholder="Tell the agent how to respond…" style="min-height:120px"></textarea>
  </label>
  <div class="bf-search" style="width:240px"><span style="flex:1">Search</span><span class="bf-kbd">⌘K</span></div>
</div>

With an icon

Wrap a bare <input> in a label.bf-input to add a leading 16px icon. It's the same component: same box, states and focus ring. The guidelines site uses it for the sidebar search and the token filter.

<label class="bf-input" style="max-width:320px">
  <i class="ph ph-magnifying-glass"></i>
  <input type="search" placeholder="Search guidelines" aria-label="Search guidelines">
</label>

States

Hover and focus are colour changes, so they use duration-hover (150ms) with ease-standard. Fields never move.

Rules

• Always show a visible label. Placeholders are examples, not labels.
• Put helper text under the field. Error text replaces helper text; don't stack both.
• Write errors that say how to fix the problem ("Enter a full email address"), not just what's wrong.
• Search in the top nav is a compact 32px variant with a ⌘K hint (.bf-search + .bf-kbd).

Code

<label className="flex flex-col gap-100">
  <span className="type-body-md-strong text-default">Organisation name</span>
  <input
    className="h-[var(--bf-input-height)] p-150 rounded-small border border-input bg-surface type-body-md text-default
               placeholder:text-subtlest hover:border-subtlest transition-colors duration-hover ease-standard
               focus:outline-none focus:border-[color-mix(in_srgb,var(--bf-brand)_46%,transparent)] focus:shadow-[inset_0_0_0_1px_color-mix(in_srgb,var(--bf-brand)_46%,transparent)]
               aria-[invalid=true]:border-status-error-dot disabled:bg-sunken disabled:text-subtlest"
    placeholder="Acme Inc."
  />
  <span className="type-body-sm text-subtlest">Shown to your customers in the help widget.</span>
</label>

<div class="bf-stack bf-gap-200">
  <label class="bf-choice"><input type="checkbox" class="bf-check" checked> Notify me when a conversation is escalated</label>
  <label class="bf-choice"><input type="checkbox" class="bf-check"> Include internal notes</label>
  <div class="bf-inline bf-gap-300" role="radiogroup" aria-label="Visibility">
    <label class="bf-choice"><input type="radio" name="vis" class="bf-radio" checked> Public</label>
    <label class="bf-choice"><input type="radio" name="vis" class="bf-radio"> Internal</label>
    <label class="bf-choice"><input type="radio" name="vis" class="bf-radio"> Private</label>
  </div>
  <label class="bf-choice"><input type="checkbox" role="switch" class="bf-toggle" checked> Notes</label>
  <label class="bf-choice"><input type="checkbox" role="switch" class="bf-toggle"> Auto-publish discoveries</label>
</div>

Specs

• Off: 1.5px border-button outline on elevation-surface.
• On: checkbox and toggle track fill with brand, the check mark uses on-brand, and the toggle handle stays border-button (ink). The radio dot is mono-1000.
• Motion: the toggle handle slides with duration-state (200ms) and ease-out, as a transition so rapid toggling retargets instead of restarting. Checkbox and radio change instantly.
• Label: body-md, with a gap of space-100 between control and label. The whole label is clickable.

Code

<label className="inline-flex items-center gap-100 type-body-md cursor-pointer">
  <input type="checkbox" role="switch" className="peer sr-only" checked={on} onChange={…} />
  <span className="relative w-[42px] h-[24px] rounded-round border-[1.5px] border-button bg-surface peer-checked:bg-brand
                   after:absolute after:top-[2.5px] after:left-[3px] after:size-[16px] after:rounded-round after:bg-[var(--bf-border-button)]
                   after:transition-transform after:duration-state after:ease-out peer-checked:after:translate-x-[17px]
                   peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-[var(--bf-focus-ring)]" />
  Notes
</label>

Accessibility

Use native inputs (type="checkbox", type="radio", and role="switch" for toggles). Group radios with role="radiogroup" or a <fieldset> and <legend>.

Four small rounded things that look alike but mean different things. Pick by what the user can do with it.

Status

<div class="bf-inline bf-gap-100">
  <span class="bf-status bf-status--info">Open</span>
  <span class="bf-status bf-status--success">In progress</span>
  <span class="bf-status bf-status--warning"><span class="bf-status__dot"></span>Unpublished changes</span>
  <span class="bf-status bf-status--warning">Blocked</span>
  <span class="bf-status bf-status--error"><span class="bf-status__dot"></span>Failed</span>
  <span class="bf-status bf-status--discovery"><span class="bf-status__dot"></span>Discovery</span>
  <span class="bf-status bf-status--neutral"><span class="bf-status__dot"></span>Draft</span>
  <span class="bf-toggle-state" data-on="true">On</span>
  <span class="bf-toggle-state">Off</span>
</div>

Specs: height 18, padding 1px 6px, gap 4, radius-round, body-sm, 8px dot (optional). Use the dot when the status sits alone. Leave it out in dense lists where the pill already reads.

Context pill & chip

<div class="bf-inline bf-gap-100">
  <button class="bf-pill" aria-label="Remove Product setup"><i class="ph ph-file-text bf-icon"></i><i class="ph ph-x bf-pill__remove"></i>Product setup</button>
  <button class="bf-pill" aria-label="Remove Salesforce - Cases"><span class="bf-src bf-src--salesforce"></span><i class="ph ph-x bf-pill__remove"></i>Salesforce - Cases</button>
  <button class="bf-chip" aria-pressed="true">Encouraging</button>
  <button class="bf-chip">Concise</button>
  <button class="bf-chip bf-chip--subtle">Formal</button>
  <span class="bf-ai-badge"><i class="ph ph-sparkle bf-icon" style="width:12px;height:12px"></i>Generated by Brainfish AI</span>
</div>

The AI badge has a yellowfin gradient hairline. Put it on any content the AI wrote that a human hasn't reviewed yet, next to the confidence text.

Code

const tone = { info: 'bg-status-info-bg text-status-info-fg', success: 'bg-status-success-bg text-status-success-fg', /* … */ };
<span className={`inline-flex items-center gap-050 h-[18px] px-075 py-px rounded-round type-body-sm ${tone[kind]}`}>
  {dot && <span className="size-[8px] rounded-round bg-status-info-dot" />}{label}
</span>

Rules

• Status text is a state ("Blocked"), never an instruction ("Unblock").
• Don't rely on colour alone. The label carries the meaning.
• Use at most one status per row in a list, plus one secondary text label (for example Open · Human requested).

<div class="bf-stack bf-gap-300">
  <div class="bf-tabs" role="tablist" aria-label="Reply as">
    <button class="bf-tab" role="tab" aria-selected="true">Slack</button>
    <button class="bf-tab" role="tab" aria-selected="false">Note</button>
  </div>
  <div class="bf-tabs" role="tablist" aria-label="Workflow view" style="background:transparent">
    <button class="bf-tab bf-tab--underline" role="tab" aria-selected="true"><i class="ph ph-tree-structure bf-icon"></i>Create</button>
    <button class="bf-tab bf-tab--underline" role="tab" aria-selected="false"><i class="ph ph-list-checks bf-icon"></i>Run history <span class="bf-tab__count">17</span></button>
  </div>
  <div class="bf-inline bf-gap-100">
    <button class="bf-control"><i class="ph ph-funnel-simple bf-icon"></i>Filter</button>
    <button class="bf-control"><i class="ph ph-arrows-down-up bf-icon"></i>Sort</button>
    <button class="bf-control">All channels <i class="ph ph-caret-down bf-icon"></i></button>
  </div>
</div>

Motion: the active tab background and shadow transition with duration-state (200ms) and ease-out. Switching tabs from the keyboard is instant.

Accessibility

Use role="tablist", role="tab" and aria-selected, and move between tabs with the arrow keys. A view control that opens a menu needs aria-haspopup="menu" and aria-expanded.

Code

<div role="tablist" className="inline-flex gap-025 p-025 rounded-small bg-sunken">
  {tabs.map(t => (
    <button key={t} role="tab" aria-selected={t === active}
      className="h-[var(--bf-control-height-sm)] px-100 py-050 rounded-small type-body-md text-default
                 transition-[background-color,box-shadow] duration-state ease-out aria-selected:bg-surface aria-selected:shadow-app">
      {t}
    </button>
  ))}
</div>

<div class="bf-inline bf-gap-400" style="align-items:flex-start">
  <div class="bf-menu" role="menu" aria-label="Page actions">
    <button class="bf-menu__item" role="menuitem"><span class="bf-inline bf-gap-100"><i class="ph ph-copy bf-icon"></i>Duplicate</span></button>
    <button class="bf-menu__item" role="menuitem"><span class="bf-inline bf-gap-100"><i class="ph ph-arrow-square-out bf-icon"></i>Open in new tab</span></button>
    <button class="bf-menu__item" role="menuitem"><span class="bf-inline bf-gap-100"><i class="ph ph-globe bf-icon"></i>Language</span><i class="ph ph-caret-right bf-icon"></i></button>
    <div class="bf-menu__divider" role="separator"></div>
    <button class="bf-menu__item" role="menuitem" style="color:var(--bf-danger-fg)"><span class="bf-inline bf-gap-100"><i class="ph ph-trash bf-icon" style="color:inherit"></i>Delete</span></button>
  </div>
  <div class="bf-menu" role="menu" aria-label="Visibility" style="width:260px">
    <button class="bf-menu__item bf-menu__item--rich" role="menuitemradio" aria-checked="true"><i class="ph ph-globe bf-icon--24 bf-icon"></i><span>Public<small>Everyone on the internet can view this article.</small></span></button>
    <button class="bf-menu__item bf-menu__item--rich" role="menuitemradio" aria-checked="false"><i class="ph ph-lock-simple bf-icon--24 bf-icon"></i><span>Internal<small>Only your team and AI agents can see this.</small></span></button>
  </div>
</div>

Specs

• Container: elevation-surface, radius-large, 1px border-input, shadow-app, padding 4, min-width 220.
• Item: height 36, padding 8, radius 6, body-md. Hover and keyboard focus fill bg-selected. Trailing caret for submenus.
• Rich item (title and description, Figma menu.dropdown.link): 24px icon, title body-md, description body-sm text-subtlest.
• Divider: 1px elevation-sunken with 4px vertical margin.
• Destructive item: danger-fg text, last in the list after a divider.
• Motion: add .bf-pop. It scales out of its trigger (transform-origin: var(--transform-origin)), from scale(0.95) and opacity 0, over duration-popover (200ms) with ease-out, and leaves the same way. If a keyboard shortcut opened it, show it instantly.

Accessibility

role="menu" and menuitem (or menuitemradio/menuitemcheckbox). Arrow keys move, Enter selects, Esc closes and returns focus to the trigger. Use a headless primitive in product code and style it with these tokens: Base UI Menu for new work (it supplies --transform-origin and the data-starting-style / data-ending-style hooks .bf-pop uses), or the Radix / React Aria equivalent if the repo already uses one. Don't hand-roll focus management.

Platform navigation has three tiers, always in the same places (see App shell):

App rail items

<div class="bf-inline bf-gap-600" style="align-items:flex-start">
  <nav class="bf-stack bf-gap-050" style="width:200px" aria-label="App">
    <a class="bf-nav-item" href="#"><i class="ph ph-tray bf-icon"></i>Inbox</a>
    <a class="bf-nav-item" href="#" aria-current="page"><i class="ph ph-book-open-text bf-icon"></i>Knowledge</a>
    <a class="bf-nav-item" href="#"><i class="ph ph-tree-structure bf-icon"></i>Workflows</a>
    <a class="bf-nav-item" href="#"><i class="ph ph-chats-teardrop bf-icon"></i>Channels</a>
    <a class="bf-nav-item" href="#"><i class="ph ph-chart-pie bf-icon"></i>Analytics</a>
  </nav>
  <nav class="bf-stack bf-gap-100" aria-label="App (collapsed)">
    <a class="bf-nav-item bf-nav-item--icon" href="#" aria-label="Inbox" aria-current="page"><i class="ph ph-tray bf-icon"></i></a>
    <a class="bf-nav-item bf-nav-item--icon" href="#" aria-label="Knowledge"><i class="ph ph-book-open-text bf-icon"></i></a>
    <a class="bf-nav-item bf-nav-item--icon" href="#" aria-label="Analytics"><i class="ph ph-chart-pie bf-icon"></i></a>
  </nav>
  <div class="bf-stack bf-gap-100" style="width:240px">
    <div class="bf-spread"><span class="bf-h5">Pages</span><span class="bf-inline bf-gap-050"><button class="bf-btn bf-btn--ghost bf-btn--icon" aria-label="Search pages" style="width:24px;height:24px"><i class="ph ph-magnifying-glass bf-icon"></i></button><button class="bf-btn bf-btn--ghost bf-btn--icon" aria-label="New page" style="width:24px;height:24px"><i class="ph ph-plus bf-icon"></i></button></span></div>
    <div class="bf-tree" role="tree">
      <div class="bf-tree-item" role="treeitem"><i class="ph ph-folder bf-icon"></i>Customers</div>
      <div class="bf-tree-item" role="treeitem" style="--level:1" data-level><i class="ph ph-folder-open bf-icon"></i>Be10x</div>
      <div class="bf-tree-item" role="treeitem" style="--level:2" data-level><i class="ph ph-file bf-icon"></i>Account Health</div>
      <div class="bf-tree-item" role="treeitem" style="--level:2" data-level aria-current="page"><i class="ph ph-file-dashed bf-icon"></i>Expansion plan</div>
      <div class="bf-tree-item" role="treeitem"><i class="ph ph-folder bf-icon"></i>CommBank</div>
    </div>
  </div>
</div>

Tree indentation is 12px per level, with 1px mono-400 guide lines. Icons show state: Folder/FolderOpen for parents, File for pages, FileDashed for drafts, FileLock for internal pages, and a Lightning marker for pages with discoveries.

Top bar

• Left: org switcher (control.org, customer logo + name + caret).
• Centre: global search (.bf-search, 32px, ⌘K).
• Right: contextual pills (for example 7 knowledge discoveries in blue-600 with white text) and Ask Brainfish (secondary button style, AI mark).

Breadcrumb

body-sm, text-subtle, slash-separated, at the top of the content column: Knowledge / Customers / Be10x.

Accessibility

• Wrap each tier in <nav aria-label>. Mark the current item with aria-current="page".
• Icon-only rail items need aria-label and a tooltip.
• The knowledge tree uses role="tree"/treeitem with aria-expanded. Arrow keys expand and collapse.

<div class="bf-stack bf-gap-300">
  <div class="bf-stack bf-gap-100" style="max-width:440px">
    <button class="bf-option"><span class="bf-option__icon"><i class="ph ph-plus-circle bf-icon bf-icon--24"></i></span><span class="bf-stack bf-gap-025"><span class="bf-body-md">Add a channel</span><span class="bf-body-sm bf-subtlest">Deploy Brainfish inside the surfaces where your users and team ask questions.</span></span></button>
    <button class="bf-option"><span class="bf-option__icon"><i class="ph ph-tree-structure bf-icon bf-icon--24"></i></span><span class="bf-stack bf-gap-025"><span class="bf-body-md">Create a workflow</span><span class="bf-body-sm bf-subtlest">Give your AI the skills to take action, like handing off to a live agent.</span></span></button>
  </div>
  <div class="bf-inline bf-gap-300" style="align-items:flex-start">
    <article class="bf-object-card">
      <header class="bf-object-card__header">
        <div class="bf-spread"><span class="bf-inline bf-gap-100"><i class="ph ph-robot bf-icon bf-icon--24"></i><span class="bf-h5">Support agent</span></span><span class="bf-toggle-state" data-on="true">On</span></div>
        <span class="bf-body-sm bf-subtlest">Answers in Slack and the help widget</span>
      </header>
      <div class="bf-object-card__body"><span class="bf-metric-label">Resolution · 30 days</span><div class="bf-metric-sm">76%</div></div>
      <footer class="bf-object-card__footer"><span class="bf-inline bf-gap-050"><i class="ph ph-warning bf-icon"></i>2 sources need attention</span><button class="bf-btn bf-btn--ghost bf-btn--sm">Open</button></footer>
    </article>
    <div class="bf-stack bf-gap-200">
      <div class="bf-node"><span class="bf-node__eyebrow">Trigger</span><span class="bf-body-md-strong">Manual</span><span class="bf-body-sm bf-subtle">Runs when you command it</span></div>
      <div class="bf-node"><span class="bf-node__eyebrow">Step 2 · Lookup</span><span class="bf-body-md-strong">Fetch HubSpot contact</span><span class="bf-body-sm bf-subtle">Search HubSpot CRM by email and return key account fields.</span></div>
      <div class="bf-inline bf-gap-100"><span class="bf-tile"><i class="ph ph-broadcast bf-icon bf-icon--32"></i></span><span class="bf-tile bf-tile--sm"><i class="ph ph-globe bf-icon bf-icon--24"></i></span></div>
    </div>
  </div>
</div>

Rules

• Whole-card click (option cards) uses a <button> or <a> as the card. Never nest another interactive element inside it.
• Object cards can contain controls (toggle, footer button). In that case the card itself isn't clickable; put an Open action in the footer.
• Don't nest a card inside a card. Use a sunken well (.bf-object-card__body) for an inner group.
• Workflow connectors are 2px brand curves with 8px brand endpoint dots on a dotted mono-400 grid.

Avatar

<div class="bf-inline bf-gap-200">
  <span class="bf-avatar">PK</span>
  <span class="bf-avatar">PK</span>
  <span class="bf-avatar bf-avatar--sm">TR</span>
  <span class="bf-avatar-stack"><span class="bf-avatar">SM</span><span class="bf-avatar">LC</span><span class="bf-avatar">+3</span></span>
</div>

• 32px default and 24px small. A 2px mono-100 ring separates stacked avatars.
• The fallback shows initials in body-sm-strong on mono-300. Never leave a blank circle.
• Admin roles add a pill (Admin, Super) next to the avatar, not a badge on it.
• alt/aria-label is the person's name.

Loaders

<div class="bf-inline bf-gap-300">
  <span class="bf-spinner"></span>
  <svg class="bf-loader" width="48" height="48" viewBox="0 0 192 192" role="img" aria-label="Loading">
    <path d="M89.3807 57.3232C78.8995 48.4005 69.8719 38.5554 62.3934 28C56.719 30.8492 51.4502 34.3872 46.6981 38.5058C55.3024 50.8448 65.5666 62.1029 77.1591 71.9277C88.3066 81.3338 105.055 81.2954 116.174 71.8642C127.894 61.8706 138.061 50.7613 146.514 38.7793C141.748 34.6039 136.457 31.0147 130.752 28.124C123.291 38.6324 114.3 48.4356 103.877 57.3232C99.6964 60.8505 93.5612 60.8506 89.3807 57.3232Z"/>
    <path d="M134.637 88.1968C143.559 77.7156 153.405 68.6879 163.96 61.2095C161.111 55.5351 157.573 50.2663 153.454 45.5142C141.115 54.1185 129.857 64.3826 120.032 75.9751C110.626 87.1226 110.665 103.871 120.096 114.99C130.089 126.71 141.199 136.877 153.181 145.33C157.356 140.564 160.945 135.273 163.836 129.568C153.328 122.108 143.524 113.116 134.637 102.693C131.109 98.5124 131.109 92.3772 134.637 88.1968Z"/>
    <path d="M104.133 135.151C114.614 144.074 123.642 153.919 131.12 164.474C136.795 161.625 142.063 158.087 146.815 153.968C138.211 141.629 127.947 130.371 116.354 120.547C105.207 111.14 88.4581 111.179 77.3398 120.61C65.6193 130.604 55.4529 141.713 47 153.695C51.7651 157.87 57.0563 161.46 62.7617 164.35C70.2221 153.842 79.2133 144.039 89.6367 135.151C93.8172 131.624 99.9524 131.624 104.133 135.151Z"/>
    <path d="M58.3232 102.647C49.4005 113.128 39.5554 122.156 29 129.634C31.8492 135.309 35.3872 140.577 39.5058 145.33C51.8448 136.725 63.1029 126.461 72.9277 114.869C82.3338 103.721 82.2954 86.9723 72.8642 75.854C62.8706 64.1335 51.7613 53.967 39.7793 45.5142C35.6039 50.2793 32.0147 55.5705 29.124 61.2759C39.6324 68.7362 49.4356 77.7274 58.3232 88.1509C61.8505 92.3314 61.8506 98.4665 58.3232 102.647Z"/>
  </svg>
  <div class="bf-stack bf-gap-100" style="width:240px"><div class="bf-skeleton" style="height:12px;width:60%"></div><div class="bf-skeleton" style="height:12px"></div><div class="bf-skeleton" style="height:12px;width:80%"></div></div>
</div>

Motion: spinners loop linearly at 600ms per turn. Under prefers-reduced-motion the spinner and skeleton slow down rather than stopping, so progress is still visible.

AI loader: Brainfish ripple

Copy this as is. It has no dependencies, so it pastes into any page, prototype or artifact. In BDG pages the CSS already ships in bdg.css, so the SVG alone is enough. The SVG is also in assets/ai/ripple-loader.svg.

<!-- Brainfish ripple loader · paste anywhere, no dependencies -->
<svg class="bf-loader" width="48" height="48" viewBox="0 0 192 192" role="img" aria-label="Loading">
  <path d="M89.3807 57.3232C78.8995 48.4005 69.8719 38.5554 62.3934 28C56.719 30.8492 51.4502 34.3872 46.6981 38.5058C55.3024 50.8448 65.5666 62.1029 77.1591 71.9277C88.3066 81.3338 105.055 81.2954 116.174 71.8642C127.894 61.8706 138.061 50.7613 146.514 38.7793C141.748 34.6039 136.457 31.0147 130.752 28.124C123.291 38.6324 114.3 48.4356 103.877 57.3232C99.6964 60.8505 93.5612 60.8506 89.3807 57.3232Z"/>
  <path d="M134.637 88.1968C143.559 77.7156 153.405 68.6879 163.96 61.2095C161.111 55.5351 157.573 50.2663 153.454 45.5142C141.115 54.1185 129.857 64.3826 120.032 75.9751C110.626 87.1226 110.665 103.871 120.096 114.99C130.089 126.71 141.199 136.877 153.181 145.33C157.356 140.564 160.945 135.273 163.836 129.568C153.328 122.108 143.524 113.116 134.637 102.693C131.109 98.5124 131.109 92.3772 134.637 88.1968Z"/>
  <path d="M104.133 135.151C114.614 144.074 123.642 153.919 131.12 164.474C136.795 161.625 142.063 158.087 146.815 153.968C138.211 141.629 127.947 130.371 116.354 120.547C105.207 111.14 88.4581 111.179 77.3398 120.61C65.6193 130.604 55.4529 141.713 47 153.695C51.7651 157.87 57.0563 161.46 62.7617 164.35C70.2221 153.842 79.2133 144.039 89.6367 135.151C93.8172 131.624 99.9524 131.624 104.133 135.151Z"/>
  <path d="M58.3232 102.647C49.4005 113.128 39.5554 122.156 29 129.634C31.8492 135.309 35.3872 140.577 39.5058 145.33C51.8448 136.725 63.1029 126.461 72.9277 114.869C82.3338 103.721 82.2954 86.9723 72.8642 75.854C62.8706 64.1335 51.7613 53.967 39.7793 45.5142C35.6039 50.2793 32.0147 55.5705 29.124 61.2759C39.6324 68.7362 49.4356 77.7274 58.3232 88.1509C61.8505 92.3314 61.8506 98.4665 58.3232 102.647Z"/>
</svg>

<style>
  .bf-loader path{
    fill:currentColor;
    opacity:0.16;
    transform-box:view-box;
    transform-origin:96px 96px;
    transform:scale(1);
    animation:bf-ripple 1.6s ease-in-out infinite;
  }
  .bf-loader path:nth-child(1){animation-delay:0.00s}
  .bf-loader path:nth-child(2){animation-delay:0.40s}
  .bf-loader path:nth-child(3){animation-delay:0.80s}
  .bf-loader path:nth-child(4){animation-delay:1.20s}
  @keyframes bf-ripple{
    0%,100%{opacity:0.16;transform:scale(1)}
    16%{opacity:1;transform:scale(0.74)}
  }
  @media (prefers-reduced-motion:reduce){
    .bf-loader path{animation:none;opacity:1;transform:scale(1)}
  }
</style>

The loader is the documented exception to the motion rules: it uses ease-in-out and a 1.6s loop because it's ambient, not a response to the user. Don't retime it or swap it for a gradient. Recolour it only through color.

Show a loader only after ~300ms of waiting, so fast responses don't flash. A fast spinner (600ms per turn) makes loading feel quicker than a slow one, even when the wait is the same.

The composer for Ask Brainfish and every "ask the AI" surface (workflow builder, article drafting). The yellowfin frame says you are talking to AI. This page is a straight copy of the Figma frame: every size, radius, colour and icon below comes from ai.prompt.

<div class="bf-stack bf-gap-200" style="max-width:395px">
  <span class="bf-ai-mark" role="img" aria-label="Ask Brainfish"></span>
  <div class="bf-prompt">
    <div class="bf-prompt__inner">
      <div class="bf-prompt__field">
        <textarea class="bf-prompt__input" rows="1" placeholder="What can we help with today?" aria-label="Ask Brainfish"></textarea>
      </div>
      <div class="bf-prompt__actions">
        <button class="bf-prompt__mode" aria-haspopup="listbox">Build<i class="ph ph-caret-down"></i></button>
        <div class="bf-prompt__tools">
          <button class="bf-prompt__tool" aria-label="Expand"><i class="ph ph-corners-out"></i></button>
          <button class="bf-prompt__tool" aria-label="Attach a file"><i class="ph ph-paperclip"></i></button>
          <button class="bf-prompt__send" aria-label="Send"><i class="ph ph-arrow-up"></i></button>
        </div>
      </div>
    </div>
  </div>
</div>

With an attached page

When the prompt is opened from a page, a tab on the top edge names it. Add bf-prompt--attached to leave room above the frame.

<div class="bf-prompt bf-prompt--attached" style="max-width:395px">
  <div class="bf-prompt__attached"><i class="ph ph-file bf-icon"></i>Expansion plan</div>
  <div class="bf-prompt__inner">
    <div class="bf-prompt__field">
      <textarea class="bf-prompt__input" rows="1" placeholder="What can we help with today?" aria-label="Ask Brainfish"></textarea>
    </div>
    <div class="bf-prompt__actions">
      <button class="bf-prompt__mode" aria-haspopup="listbox">Build<i class="ph ph-caret-down"></i></button>
      <div class="bf-prompt__tools">
        <button class="bf-prompt__tool" aria-label="Expand"><i class="ph ph-corners-out"></i></button>
        <button class="bf-prompt__tool" aria-label="Attach a file"><i class="ph ph-paperclip"></i></button>
        <button class="bf-prompt__send" aria-label="Send"><i class="ph ph-arrow-up"></i></button>
      </div>
    </div>
  </div>
</div>

Context pills

Sources the AI will read. The default state shows the source logo. On hover or keyboard focus the pill turns mono-300 and an X replaces the logo; clicking removes the source.

<div class="bf-inline bf-gap-200">
  <button class="bf-pill" aria-label="Remove Salesforce - Cases"><span class="bf-src bf-src--salesforce"></span><i class="ph ph-x bf-pill__remove"></i>Salesforce - Cases</button>
  <span class="bf-pill is-remove"><span class="bf-src bf-src--salesforce"></span><i class="ph ph-x bf-pill__remove"></i>Salesforce - Cases</span>
</div>

Specs

Gradient. The prompt uses --bf-gradient-yellowfin-prompt (169.68deg, stops 7.35 / 42.81 / 66.91 / 82.59%), which is how Figma draws yellowfin on this 395 × 106 frame. Other AI surfaces keep --bf-gradient-yellowfin.

Palette, not semantic. Figma binds the mode select, send button and pills to mono-100, mono-200 and mono-300 directly. BDG copies that exactly; they're logged as candidates for semantic variables in Figma fixes.

Behaviour

• Send stays the same grey in every state in Figma. Treat it as disabled (aria-disabled) until there's input. Enter sends, Shift+Enter adds a new line.
• Hover on the mode select and tools fills bg-hover, only on devices with a fine pointer. Figma has no hover state, so this is a BDG addition.
• Hit area. The 16px tools get a 4px invisible pad on every side (24px target), the most the 8px gap allows.

Voice

The greeting introduces Ask Brainfish in one or two short sentences and says what it can do. Keep it under 40 words.

Don'ts

• Don't use the gradient frame for non-AI inputs.
• Don't round all four corners the same. The 16 / 8 split is the shape.
• Don't animate the gradient while idle. While generating, show the AI loader instead.
• Don't put a source pill inside the prompt. Pills sit beside or above it, as in the Figma frame.

<div class="bf-stack bf-gap-300" style="max-width:640px">
  <div class="bf-inline bf-gap-150" style="align-items:flex-start;flex-wrap:nowrap">
    <span class="bf-avatar">PK</span>
    <div class="bf-message bf-message--bubble bf-stack bf-gap-100" style="flex:1">
      <span>Can I talk to a human please? I need to reset my 2FA and the steps aren't working.</span>
      <span class="bf-body-sm bf-subtlest">2m ago</span>
    </div>
  </div>
  <div class="bf-card bf-stack bf-gap-200" style="padding:0;overflow:hidden">
    <div class="bf-spread" style="padding:8px 16px 0">
      <div class="bf-tabs"><button class="bf-tab" aria-selected="true">Slack</button><button class="bf-tab" aria-selected="false">Note</button></div>
      <button class="bf-btn bf-btn--ghost bf-btn--sm"><i class="ph ph-users bf-icon"></i>Co-author</button>
    </div>
    <div class="bf-stack bf-gap-150" style="padding:0 16px">
      <span class="bf-inline bf-gap-100"><span class="bf-ai-badge"><i class="ph ph-sparkle bf-icon" style="width:12px;height:12px"></i>Generated by Brainfish AI</span><span class="bf-body-sm bf-subtlest">Confidence 68% · Awaiting human review before sending</span></span>
      <p class="bf-body-md" style="margin:0">Hi Priya, I understand you'd like to speak with a human agent. To reset your authenticator, go to Account Settings → Security → Two-Factor Authentication.</p>
    </div>
    <div class="bf-spread bf-sunken" style="padding:8px 16px">
      <span class="bf-inline bf-gap-100"><i class="ph ph-paperclip bf-icon"></i><i class="ph ph-tree-structure bf-icon"></i></span>
      <span class="bf-inline bf-gap-100"><button class="bf-btn bf-btn--secondary"><i class="ph ph-trash bf-icon"></i>Discard</button><button class="bf-btn bf-btn--primary"><i class="ph ph-paper-plane-tilt bf-icon"></i>Send</button></span>
    </div>
  </div>
</div>

Rules

• Customer messages: a bubble on surface with shadow-raised and radius-xlarge, with the avatar on the left and a timestamp in body-sm text-subtlest.
• Transcript blocks (Analytics, convos.user): a flat mono-100 card with a border-input outline and radius-large.
• AI drafts always carry the AI badge and a confidence line until a human sends them.
• The composer's primary action is Send. Discard is secondary. Resolve in the conversation header is the view's other primary action, and only one of them should be filled at a time. In Platform v2.1 both are filled; see Figma fixes.

Every Platform screen sits in the same frame. Learn this once and every page is a matter of filling the canvas.

┌───────────────────────────────────────────────────────────── nav.top 48 ─┐
│ [Org ▾]                    [ Search      ⌘K ]          [Discoveries] [AB] │
├──────────┬──────────────────────────────────────────────────────────────┐ │
│ nav.side │ main canvas: surface · radius 16 · shadow-app                 │ │
│ 200 / 48 │ ┌ nav.page 240 ─┬ content (padding 24) ──────────────────────┐│ │
│          │ │ Title  🔍 +   │                                            ││ │
│ Inbox    │ │ list…         │                                            ││ │
│ Knowledge│ │               │                                            ││ │
│ …        │ └───────────────┴────────────────────────────────────────────┘│ │
│ (?)      │                                                     gutter 8 →│ │
└──────────┴──────────────────────────────────────────────────────────────┘─┘
  cream + lava lamp behind everything

Configurations

<div class="bf-app" data-nav="collapsed" style="height:420px;border-radius:12px;--bf-nav-page-width:180px">
  <div class="bf-lavalamp"></div>
  <header class="bf-nav-top">
    <span class="bf-inline bf-gap-050 bf-body-md"><span class="bf-avatar bf-avatar--sm">M</span>Malwarebytes <i class="ph ph-caret-down bf-icon"></i></span>
    <span class="bf-search" style="width:200px"><span style="flex:1">Search</span><span class="bf-kbd">⌘K</span></span>
    <button class="bf-btn bf-btn--secondary bf-btn--sm"><i class="ph ph-sparkle bf-icon"></i>Ask Brainfish</button>
  </header>
  <nav class="bf-app__side" aria-label="App">
    <div class="bf-stack bf-gap-100">
      <a class="bf-nav-item bf-nav-item--icon" href="#" aria-label="Inbox" aria-current="page"><i class="ph ph-tray bf-icon"></i></a>
      <a class="bf-nav-item bf-nav-item--icon" href="#" aria-label="Knowledge"><i class="ph ph-book-open-text bf-icon"></i></a>
      <a class="bf-nav-item bf-nav-item--icon" href="#" aria-label="Analytics"><i class="ph ph-chart-pie bf-icon"></i></a>
    </div>
    <a class="bf-nav-item bf-nav-item--icon" href="#" aria-label="Help"><i class="ph ph-question bf-icon"></i></a>
  </nav>
  <main class="bf-app__main">
    <aside class="bf-app__pagenav">
      <div class="bf-spread"><span class="bf-h5">Inbox</span><i class="ph ph-funnel-simple bf-icon"></i></div>
      <div class="bf-stack bf-gap-050">
        <div class="bf-tree-item" aria-current="page">Priya K.</div>
        <div class="bf-tree-item">Sarah M.</div>
        <div class="bf-tree-item">Tom R.</div>
      </div>
    </aside>
    <section class="bf-app__content bf-stack bf-gap-200">
      <div class="bf-breadcrumb">Inbox / Priya Kununjibar</div>
      <div class="bf-spread"><h3 class="bf-h4">Priya Kununjibar</h3><button class="bf-btn bf-btn--primary"><i class="ph ph-check-circle bf-icon"></i>Resolve</button></div>
      <div class="bf-inline bf-gap-100"><span class="bf-status bf-status--info">Open</span><span class="bf-body-sm bf-subtle">Human requested</span></div>
    </section>
  </main>
</div>

Rules

• One canvas. All content lives inside .bf-app__main. Nothing sits directly on the cream except navigation.
• Page nav is optional. Settings and Analytics may use .bf-app__main--single.
• Design width is 1440. Below 1280, collapse the rail. Below 1024, hide the page nav behind a toggle. Mobile isn't a Platform target yet.
• Panel motion: Ask Brainfish is a drawer. It slides in from the right with .bf-drawer (duration-drawer 500ms, ease-drawer) and leaves the way it came. When a keyboard shortcut opens it, it appears instantly, because keyboard actions never animate.

Code (React + Tailwind)

<div data-nav={collapsed ? 'collapsed' : undefined}
     className="relative isolate grid h-screen overflow-hidden bg-app pr-100 pb-100
                grid-rows-[var(--bf-nav-top-height)_1fr]
                grid-cols-[var(--bf-nav-side-width)_1fr] data-[nav=collapsed]:grid-cols-[var(--bf-nav-side-width-collapsed)_1fr]">
  <LavaLamp />
  <TopBar className="col-span-full" />
  <AppRail />
  <main className="grid min-h-0 grid-cols-[var(--bf-nav-page-width)_1fr] overflow-hidden rounded-xlarge bg-surface shadow-app">
    <PageNav className="border-r border-input p-200" />
    <section className="min-w-0 overflow-auto p-300">{children}</section>
  </main>
</div>

Start every new screen by picking one of these. If none fits, that's a design conversation, not a one-off.

1. List–detail

Used by: Inbox, Channels, Workflows list. Page nav holds the list (rows 56–64px, avatar or icon, title in body-md-strong, preview in body-sm text-subtle, status pill). The selected row gets bg-selected and a 4px brand bar on the left edge. Content shows the selected item: header (title h4, meta row, actions right-aligned with one primary), then the body.

2. Document

Used by: Knowledge article and editor. Breadcrumb, then title (h3) with a status and actions row on the right (Unpublished changes · 6h ago · Edit · Info · Publish). Prose is body-lg at a max of 65ch. Suggestion cards float in the right gutter (.bf-card--raised, 200px). Inline AI diffs use status-error-bg with strike-through for removed text and status-info-bg with a 1px blue-600 outline for added text.

3. Canvas

Used by: Workflow builder. Rail collapsed. Header: title h4 with Run (secondary) and Save (primary). Underline tabs (Create / Run history) sit on a dotted mono-400 grid on elevation-sunken. Nodes are joined by 2px brand curves. Zoom controls sit at the bottom left. The AI builder docks on the right as the Ask Brainfish panel.

4. Settings

Used by: My account, Organisation, Members, Billing, Usage. The page nav lists sections. Content is a single column at max 640px. Each section is an h5 title, a body-md text-subtle description, then fields with a gap of 24. Toggles apply immediately; everything else saves with one primary button at the bottom of the section.

5. Empty state

Used by: Channels day 1, Knowledge day 1, Inbox before a channel is connected.

Meet your users where they are

Add channels to deploy Brainfish inside your product, help center, or support tools.

Add a channelDeploy Brainfish where your users ask questions. Create a workflowGive your AI the skills to take action.

The recipe: a byth watermark with a radial mask, then a brand-tinted icon (48px), a Fraunces h1 headline (a benefit, not "No channels yet"), one or two lines of body-md text-subtle, and 1–3 option cards. It sits centred, max 440px wide.

BDG motion follows Emil Kowalski's animation standards (from his animate and review-animations skills, MIT licensed), mapped onto BDG tokens and components. The agent skills brainfish-animate (build), brainfish-review-motion (review) and brainfish-improve-motion (audit) enforce the same rules.

The short version: most UI should barely move. When something does move, it uses a strong ease-out curve, takes less than 300ms, animates only transform and opacity, and never runs on a keyboard action.

1. Should it animate at all?

Answer this before choosing a curve. Sometimes the right result is no animation at all.

2. What is it for?

Name the purpose in one word. If you can't, don't build it.

• Feedback: the interface heard you (button press).
• Spatial consistency: where something came from or went (a menu grows out of its trigger, the panel slides in from the right and leaves to the right).
• State indication: a state changed (toggle, tab indicator).
• Preventing a jarring change: content would otherwise teleport (a toast arriving).
• Explanation: showing how something works (onboarding, marketing only).
• Delight: only for rare or first-time moments.

Data people are reading or acting on doesn't move for style. Analytics charts, Inbox lists and article text stay still.

3. Easing

Never use ease-in on UI. It starts slowly, which delays the exact moment the user is watching. A 200ms ease-out feels faster than a 200ms ease-in. The built-in CSS keywords are too weak for deliberate motion, which is why the tokens are custom curves.

<div class="bf-stack bf-gap-150" data-motion-demo>
  <div class="bf-inline bf-gap-100">
    <button class="bf-btn bf-btn--secondary bf-btn--sm" data-run="ease-out">Play ease-out (BDG)</button>
    <button class="bf-btn bf-btn--secondary bf-btn--sm" data-run="ease-in">Play ease-in (don't)</button>
  </div>
  <div class="bf-sunken" style="border-radius:8px;padding:8px;position:relative;height:56px">
    <div data-dot style="position:absolute;left:8px;top:8px;width:40px;height:40px;border-radius:8px;background:var(--bf-brand);border:1px solid var(--bf-border-button)"></div>
  </div>
  <p class="bf-body-sm bf-subtlest" style="margin:0">Both run for 250ms. The ease-out version feels faster because it moves straight away.</p>
</div>

4. Duration

UI motion stays at or under 300ms. Only drawers and toasts go longer, and each has a reason. A 180ms menu feels more responsive than a 400ms one. Exits can be about 20% faster than entrances, larger elements can take a little longer than small ones, and longer travel warrants a longer duration.

5. Properties

• Animate transform and opacity only. They skip layout and paint and run on the GPU. clip-path is allowed too. height is tolerated for accordions only.
• Never transition: all. Name the properties.
• Never start from scale(0). Start from scale(0.95) with opacity 0. Nothing in the real world appears from nothing.
• Popovers grow out of their trigger: transform-origin: var(--transform-origin) (Base UI supplies it). Modals are the exception and stay centred.
• Use percentages in translate(). translateY(100%) moves an element by its own height, whatever its content.

6. Interruption and exit

• Use transitions, not keyframes, for anything that can fire twice in a second (toasts, toggles, tabs). Transitions pick up from where they are; keyframes restart from zero.
• Exit the way you entered. The Ask Brainfish panel enters from the right and leaves to the right.
• Make timing asymmetric where the user is deciding. A hold-to-confirm fills slowly (2s linear) and snaps back fast on release (200ms ease-out).
• Use springs for gestures (drag, swipe), because they carry velocity through an interruption: { type: "spring", duration: 0.5, bounce: 0.2 } in Motion. Avoid bounce in product UI.

All motion tokens

Hover a row to play it. Durations use ease-out; easings run at 500ms so the curve is visible.

Recipes (BDG classes)

Every recipe is in bdg.css. In product code, use the Tailwind equivalents.

<div class="bf-inline bf-gap-300" style="align-items:flex-start">
  <div class="bf-stack bf-gap-100" style="position:relative">
    <button class="bf-btn bf-btn--secondary" data-toggle-target="demo-menu"><i class="ph ph-dots-three-vertical bf-icon"></i>Page actions</button>
    <div class="bf-menu bf-pop" id="demo-menu" hidden style="--transform-origin: top left">
      <button class="bf-menu__item">Duplicate</button>
      <button class="bf-menu__item">Move to…</button>
    </div>
  </div>
  <button class="bf-btn bf-btn--danger bf-hold"><span class="bf-hold__fill"></span><i class="ph ph-trash bf-icon"></i>Hold to delete</button>
  <div class="bf-stack bf-gap-100">
    <button class="bf-btn bf-btn--ghost bf-btn--sm" data-replay="demo-stagger"><i class="ph ph-play bf-icon"></i>Replay stagger</button>
    <div class="bf-stack bf-gap-050 bf-stagger" id="demo-stagger" style="width:220px">
      <div class="bf-card" style="padding:8px 12px">Connect a channel</div>
      <div class="bf-card" style="padding:8px 12px">Upload your docs</div>
      <div class="bf-card" style="padding:8px 12px">Invite your team</div>
    </div>
  </div>
</div>

Never ship

Reduced motion

Reduced motion means fewer and gentler animations, not none. bdg.css keeps opacity and colour transitions and drops movement: the stamp no longer shifts, popovers fade without scaling, and the panel fades instead of sliding. Spinners keep turning so progress stays visible.

const reduce = useReducedMotion(); // Motion
const closedX = reduce ? 0 : '100%';

Checking the feel

Some things can't be judged from code: crossfades, a spring's bounce, or how opacity and height interact as a list grows. Play the animation at 2–5× its duration or in the DevTools Animations panel, step through it frame by frame, test gestures on a real device, and look again the next day.

Prototypes should look like the product, so feedback is about the idea and not the styling. BDG gives you the real tokens and components as plain CSS, so a prototype is a single HTML file.

With an AI agent (fastest)

With the brainfish-design skill installed in your agent, describe the screen and name the pattern:

Prototype the Inbox when a customer asks for a human. Use the BDG list–detail pattern in the app shell, with 6 conversations in the page nav and the AI draft composer open.

Using BDG, make a clickable prototype of the Knowledge empty state, then the first article after upload.

Good prompts name a page pattern (list–detail, document, canvas, settings, empty state), the theme if it's not default, and the realistic content to use. The skill starts from templates/prototype.html, uses only .bf-* classes and tokens, and checks itself against the review checklist.

By hand

1. Copy skills/brainfish-design/templates/prototype.html. It already links fonts, tokens, components and icons, and has the app shell.
2. Fill the canvas with components from this site. Every example has a Copy button.
3. Use realistic Brainfish content (customer names, real-sounding articles), never lorem ipsum.
4. Switch data-theme="ballet" on <html> to see the screen in the Ballet theme for free.

Rules for prototypes

• Only .bf-* classes and var(--bf-*) tokens for visual values. Inline style is fine for layout (width, grid), not for colour, type or radius.
• One primary button per view.
• Interactions that matter to the idea should work: tabs switch, panels open. Fake the data, not the behaviour.
• Name the file after the question it answers: inbox-human-handoff.html, not prototype-v3.html.

BDG ships as a family of small Agent Skills: plain folders with a SKILL.md file, an open format that works with whichever model or tool your team prefers. Each skill does one job and loads only when that job comes up, so your agent carries the right rules without filling its context with everything else. brainfish-design is the entry point. It owns the tokens, components and layouts, and hands off to a sibling when the job is specifically theirs.

The taste and motion skills are adapted from Emil Kowalski's skills (MIT). His rules are kept intact and mapped onto BDG tokens, with one deliberate exception: BDG buttons keep the stamp press instead of scale(0.97).

The family

Start here

Taste & motion

Build & test

Brand

Auto skills load on their own when a request matches their description. Explicit skills only run when you ask for them by name (for example "use brainfish-review-motion on this diff"), because they're heavy or opinionated.

Ask like this

Install

The skills are model-agnostic. Any agent that supports the Agent Skills format can use them; the only difference between tools is which folder they read.

Run npm run build after changing anything in guidelines/ or tokens/. It refreshes brainfish-design/references/, the .agents/skills/ and .claude/skills/ copies and the zips.

Set up (once per repo)

1. Vendor BDG. Add this repo as a git submodule at vendor/bdg, or publish dist/ as an internal package (@brainfish/bdg).
2. Import tokens once, globally: @import 'vendor/bdg/dist/tokens.css';
3. Add the preset.
   • Tailwind v3: presets: [require('./vendor/bdg/dist/tailwind-preset.cjs')]
   • Tailwind v4: @import "./vendor/bdg/dist/tailwind-theme.css";
4. Set the theme on <html data-theme="bf" data-mode="light">.
5. Load fonts: Fraunces 400, Geist 400/600, Geist Mono 400.
6. Add the skill for your coding agent: copy skills/brainfish-design to .agents/skills/brainfish-design in the product repo (or the skills folder your agent reads, see Agent skills).

The preset replaces Tailwind's default colours, spacing and radii. bg-blue-500 and p-4 stop working, which is deliberate. It's the fastest way to find hard-coded values.

Class cheat sheet

Changing UI: the rules

1. Find the component recipe on this site first. Match its tokens exactly.
2. No raw values. No hex codes, no px outside layout dimensions, no ms. npm run check in this repo flags them in guidelines; add the same lint to the product (see below).
3. Semantic first. If you reach for a palette step, check whether a semantic token should exist and propose it.
4. Accessibility is part of done: labels, focus states, aria-current, contrast (≥ 4.5:1 for text).
5. Screens match Figma; Figma matches BDG. If they disagree, BDG wins for tokens and Figma wins for layout intent. Log it in Figma fixes.

Recommended lint

// eslint: flag raw colours in className strings
'no-restricted-syntax': ['warn', { selector: "Literal[value=/#[0-9a-fA-F]{3,8}\\b/]", message: 'Use a BDG token, not a hex value.' }]

// stylelint
{ "rules": { "color-no-hex": true, "declaration-property-value-disallowed-list": { "/^(transition|animation)/": ["/\\d+ms/"] } } }

Migrating an existing screen

Ask your agent: "Migrate src/features/inbox/ConversationHeader.tsx to BDG: replace raw values with tokens, match the Button and Status recipes, and list anything without a token." The skill works through the product-code workflow and reports what it couldn't map.

Not everything is the product. Internal dashboards, one-pagers, calculators and AI-generated artifacts should still feel like Brainfish, just with more room to breathe.

Defaults for non-product pages

With an AI agent

Make an internal dashboard of weekly resolution rate by customer, BDG artifact styling, data below.

The skill uses templates/artifact.html (no app shell, cream page, cards) and keeps everything self-contained: tokens and components inlined, Phosphor icons as inline SVG, Google Fonts only.

Don't

• Don't use the app shell (rail and canvas) for things that aren't the product. It makes them look like a feature.
• Don't use the lava-lamp or yellowfin gradient for decoration.
• Don't invent taglines. For marketing copy, use the brainfish-brand skill.

Run this on any screen, prototype or artifact. Your agent runs the same list when you ask it to "review this against BDG".

Tokens

• No raw hex, rgb, px for colour/type/radius/shadow, or ms values. Only tokens.
• Semantic tokens used where they exist (text-subtle, not mono-700).
• Spacing is on the scale (2, 4, 6, 8, 12, 16, 24, 32 …). No 10px, 14px or 20px.

Hierarchy

• One filled brand button in the view.
• Fraunces appears only at h1/h2 sizes. Everything else is Geist.
• Body text is body-md in UI and body-lg in reading contexts. Nothing smaller than 12px.
• Colour carries no meaning on its own. Every status has a label.

Components

• Every control matches a BDG recipe (stamp shadow on buttons, 44px fields, round pills).
• Icons are Phosphor Regular at 16, 20 or 24px.
• The yellowfin gradient appears only on AI surfaces.
• The logo is embedded from the SVG file, the correct variant for the background.

Layout

• Product screens use the app shell and one of the five page patterns.
• Content sits inside the canvas. Only navigation sits on cream.
• Prose is no wider than 65ch.

Motion

• Nothing animates on a keyboard shortcut or a 100+/day action (⌘K, tab switching from the keyboard, list navigation).
• Every animation has a named purpose: feedback, spatial consistency, state, preventing a jarring change.
• Easing and duration are BDG tokens. No ease-in, no transition: all, UI motion ≤ 300ms.
• Only transform and opacity animate. Nothing enters from scale(0). Menus grow from their trigger.
• Hover motion is gated to fine pointers. Reduced motion keeps fades and drops movement.

Accessibility

• Text contrast ≥ 4.5:1 (check dist/contrast-report.json for token pairs).
• Visible focus on every interactive element (focus-ring).
• Icon-only buttons have aria-label. Current nav items have aria-current.
• Works with the keyboard alone: tab order, Esc closes, arrows in menus and tabs.

Taste details

• Numbers that line up use tabular-nums. Truncation uses … via CSS.
• Small controls keep a 44px hit area.
• Tested with worst-case data (brainfish-break-ui): long names, empty states, huge counts.

Content

• Real content, no lorem ipsum.
• Buttons are verbs. Errors say how to fix the problem.
• Brainfish voice: direct, specific, no "revolutionise" or "leverage".

BDG changes the way the product changes: small, reviewed, versioned. Anyone can propose a change.

What kind of change is it?

Proposal template

### Component: <name>
**Problem:** what users or builders can't do today (link a screen).
**Why not an existing component:** which ones you tried.
**Anatomy & tokens:** sketch + the tokens it uses (no raw values).
**States:** rest / hover / pressed / focus / disabled / loading / error.
**Accessibility:** role, keyboard, labels.
**Figma:** link to the frame.

Status levels

• proposed: documented for discussion, not for use in product.
• beta: usable, and the API may change. Changes are announced in the CHANGELOG.
• stable: breaking changes need a major version and a migration note.
• deprecated: still works, with a replacement named. Removed in the next major.

Versioning

Semver on the dist/ output:

• patch: value tweaks within a token's intent, doc fixes.
• minor: new tokens, components or variants.
• major: renamed or removed tokens or classes, or a changed default theme.

Every PR updates CHANGELOG.md.

Writing guidelines

Each page has front matter (title, section, order, summary, figma, status) and this shape: when to use → anatomy → variants/states → tokens → code (prototype + product) → accessibility. Use ```html preview fences for live examples: the site renders them live with a code view, and the skill reads them as recipes. Use only .bf-* classes and var(--bf-*) tokens in examples.

npm run check fails if a guideline contains a raw hex value outside a code sample about hex values.

Review

Design Engineering owns tokens/, src/ and scripts/. Product Design owns guidance. Changes to the default theme need both.

BDG ships with these decisions so code is consistent today. Each one should be fixed at the source (Figma), then re-exported, and the BDG workaround removed. Found during the v0.1 audit of 🐠 Foundations, Components and Platform v2.1 (October 2026).

0.2.0 · 2026-10-23

Motion replaced with Emil Kowalski's animation standards (MIT), mapped to BDG tokens:

• Easing: --bf-ease-out cubic-bezier(0.23, 1, 0.32, 1), --bf-ease-in-out cubic-bezier(0.77, 0, 0.175, 1), --bf-ease-drawer cubic-bezier(0.32, 0.72, 0, 1), --bf-ease-standard, --bf-ease-linear. --bf-ease-in removed.
• Durations by element: tooltip 125, hover 150, press 160, popover 200, state 200, modal 250, toast 400, drawer 500ms; --bf-stagger 50ms. The old instant/fast/base/slow/page tokens are removed (breaking).
• New classes: .bf-pop, .bf-tooltip, .bf-modal, .bf-backdrop, .bf-drawer, .bf-toast, .bf-stagger, .bf-hold. .bf-enter-* classes removed (breaking).
• Hover motion gated to fine pointers (hover-fine: Tailwind variant). Reduced motion keeps fades and drops movement instead of zeroing everything.
• The stamp press stays as the BDG exception to scale(0.97), retimed to 160ms.

Taste: new Taste page; prose width 65ch (was 72ch); 44px hit area token.

Skills: 12 skills adapted from Emil Kowalski's set (brainfish-taste, brainfish-animate, brainfish-review-motion, brainfish-improve-motion, brainfish-find-motion, brainfish-motion-performance, brainfish-motion-vocabulary, brainfish-variants, brainfish-break-ui, brainfish-pick-library, brainfish-apple-design, brainfish-mobile-web), plus brainfish-brand now versioned in the repo. New Agent skills page; per-skill zips in dist/skills/.

Themes: BF and Ballet only. brainfish-brand now uses the BF lime brand accent.

0.1.0 · 2026-10-23

First release, built from 🐠 Foundations, Components and Platform v2.1.

Tokens

• 100 palette steps (10 hues × 10), 14 spacing steps, 4 radii, from the Figma Foundations variable collection.
• 48 semantic tokens × 2 themes (bf default, ballet) × 2 modes (light, dark).
• 16 text styles, 5 shadows, 5 durations, 4 easings, layout and z-index tokens, 9 gradients.
• Outputs: tokens.css, tokens.json, a Tailwind v3 preset, a Tailwind v4 theme, and a contrast report.

Components (src/bdg.css + guidelines): button, form fields, checkbox/radio/toggle, status/pill/chip, tabs and view controls, menu, navigation, cards, avatar and loaders, AI prompt, conversation (beta).

Layouts: app shell (4 configurations), 5 page patterns. Motion: duration and easing system, stamp interaction.

Skill: brainfish-design with prototype, product-code, artifact and review workflows.

Known drift: 16 items logged in Figma fixes.