| version | alpha | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | open-bridge | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| description | Editorial minimalism meets enterprise gravitas, high-contrast neutrals with a single violet-indigo gradient accent. A fork adds its own brand under `identity/designs/` and leaves this file as it ships. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| colors |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| typography |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| rounded |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| spacing |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| components |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| site |
|
This file is the Bridge's default design and the index to every other one. A Bridge can hold more:
one file per brand under identity/designs/<id>.md, in this same format, each with its own scope:.
An organisation's brand declares scope: org and reaches every member Bridge through the org
overlay. Nobody edits this file for it.
Which design a piece of work uses is resolved, never picked by hand. The first step that answers wins:
| Step | Source | Typical case |
|---|---|---|
| 1 | --design <id> on the generator |
a one-off page in another brand |
| 2 | a target repository with its own DESIGN.md |
a deck written into a website repository |
| 3 | design_ref: in workflow/contexts/<ctx>.yaml |
every deliverable of one organisation |
| 4 | design_ref: in identity/personas/<id>.yaml |
mail sent under a second identity |
| 5 | branding.design: in the active themes/<name>.yaml |
the instance default |
| 6 | this file | a Bridge with no further design |
A context or persona that must not wear the theme's design says design_ref: default: resolution
stops there, at this file (freelance work under a second identity in an organisation's Bridge).
default is reserved and never a design id; design_ref: null means not set.
python3 scripts/designs.py list # every design, its scope, what it is for, who points at it
python3 scripts/designs.py resolve --context <ctx> # the file that applies
What else shapes a visual, and where it lives:
| What | Where |
|---|---|
| colours, type and shapes of a brand | this file, identity/designs/<id>.md |
| how one medium applies a design | the generator's map, for example skills/html-slides/presets/design.map.yaml |
| behaviours every visual has (theme toggle, sources) | rules/visual-output.md |
| terminal logo and vocabulary | themes/<name>.yaml |
| mail signature | identity/mail-footers/ |
Editorial Minimalism meets Enterprise Gravitas. This visual identity
communicates strategic clarity through restraint: generous whitespace, hairline
borders, and a single gradient accent that signals transformation without
shouting. The feel is that of a premium consultancy whitepaper crossed with a
modern software product: composed, confident, deliberately unflashy. A fork
with a brand of its own describes it in identity/designs/<id>.md (see
Designs in this Bridge above) and leaves this file as it ships.
Every design choice should reinforce one idea: complex technology, explained with calm authority. Avoid dark patterns, hype gradients on every surface, or dense dashboards. Let the grid breathe.
Signature moves
font-weight: 300on all large headings — lightness is the brand voice.- A purple→indigo gradient (
#667EEA → #764BA2) reserved only for accent words inside headings, the wordmark, and decorative geometric icons. Never on body copy, borders, or backgrounds. - Section rhythm alternates pure white with
bg-gradient-subtle(near-white to#F9FAFB). No colored section backgrounds. - Content is centered with
max-width: 48rem–80remwrappers. Edge-to-edge layouts are reserved for the hero only.
High-contrast neutrals do 95% of the work. The accent gradient is a supporting character — present, never dominant.
- Primary
#111827— Deep ink for all headlines, body copy, and primary buttons. Use on white/subtle surfaces only. - Secondary
#6B7280— Slate gray for captions, metadata, icon strokes, and muted UI chrome. - Surface
#FFFFFF— Default page background. Pairs withsurface-subtle #F9FAFBfor the alternating-section rhythm. - Border
#E5E7EB— 1px hairlines on cards, nav, and dividers. Never heavier than 1px in light mode. - Accent Gradient
#667EEA → #764BA2— The brand signature gradient. Applied viabackground-clip: textto one or two accent words per headline, to the secondary half of the wordmark, and as the fill for the six geometric feature icons. Using it anywhere else cheapens it. - Feature gradients — Each competency icon gets its own 2-stop gradient
drawn from the purple/blue/orange families (
feature-*-from/to). These are decorative only; never use them as button or text colors.
When .dark is active on <html>, swap surfaces to the dark-* tokens:
surface → #111827, surface-subtle → #1F2937, on-surface → #D1D5DB. The
accent gradient lifts to #A78BFA → #818CF8 so it stays legible against dark
backgrounds. The brand voice does not change — it is still restrained, still
editorial.
The slate text lifts as well, from gray-500 to gray-400 (secondary and
on-surface-muted → #9CA3AF). Every text token has a dark counterpart, and a
light value is never reused as text on a dark ground.
- Primary on Surface: 16.1:1 (AAA)
- On-Surface on Surface: 9.3:1 (AAA)
- Secondary on Surface: 4.8:1 (AA body)
- Dark mode, Secondary (
#9CA3AF) on Surface (#111827): 7.0:1 (AA body) - Dark mode, On-Surface (
#D1D5DB) on Surface (#111827): 12.0:1 (AAA) - On-Primary (white) on Primary: 16.1:1 (AAA)
Gradient text must always sit on solid surface or surface-subtle — never
over imagery or color. The accent gradient is not a guaranteed-contrast color
and must not be used for interactive text targets without a solid fallback.
The GitHub Pages site under docs/ wears a second palette of its own: ink
#0F2A4A on a warm #FAF7F3 surface, one blue accent #2D5B8F (dark:
#5690D2 on #101419), flat shadows, and Playfair Display for h1, h2 and
the wordmark beside Inter for everything else. Its tokens are the site: block
in the front matter, named after the custom properties in
docs/assets/brand.css that carry them. It describes this repo's own site and
nothing a skill generates: mail, slides, PDFs and dashboards keep reading
colors: and typography:. scripts/check-site-basics.py fails CI when a
value in one file differs from the other, so a change lands in both or not at
all. Both fonts are self-hosted under docs/assets/fonts/.
Inter is the sole typeface, weights 300 / 400 / 500 / 600 / 700.
Never load fonts from Google Fonts (or any third-party font CDN). It is a privacy/GDPR violation — the CDN logs the visitor's IP on every page. Inter is open (SIL OFL); ship it self-hosted (a local
@font-facewith the woff2 bundled or referenced relative to the page), or fall back to the system stackInter, -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, Roboto, sans-serif(San Francisco on macOS is the closest cousin). Nofonts.googleapis.com/fonts.gstatic.comlinks, ever — in any generated HTML, email, slide, or dashboard.
The defining rule: large = light. Any text at 24px or above uses
font-weight: 300 unless it is a card title (500) or button label (500). This
inversion of the usual "big = bold" convention is the single most important
typographic signal of the brand.
- Display (72px/300) — Hero headline. One per page.
- H1 (48px/300) — Section headlines. Always paired with a subtitle.
- H3 (24px/500) — Card and step titles. Medium weight re-establishes hierarchy inside dense grids.
- Body-xl (20px/300) — Hero subtitle and section intros. Light weight so it reads as continuation of the headline, not as a separate block.
- Body-md (16px/400) — All default prose.
line-height: 1.6is mandatory. - Stat-display (36px/300) — KPIs. Pair with a 14px uppercase
label-capsunderneath for the classic consulting-stat presentation.
Headlines commonly mix weights inline: <span>Digital Transformation</span>
in font-weight: 300 followed by <span class="text-gradient">accelerate intelligence</span> in font-weight: 400. The gradient span always gets a
one-step-heavier weight so it reads as the focal point.
- Container:
max-width: 80rem(1280px) withpadding-inline: 24px. Centered. Hero content narrows further tomax-width: 64rem(5xl). - Section rhythm: vertical padding is always
96pxtop and bottom (py-24). Never less. Alternatesurfaceandsurface-subtlebackgrounds to create cadence. - Grid: feature and team cards use CSS grid with
gap: 32px. Breakpoints at 1 / 2 / 3 columns (md/lg) for features, 1 / 2 / 5 for team. - Nav: fixed, 80px tall, full-width translucent (
backdrop-filter: blur), 1px bottom border. Content underneath gets no top padding — the hero absorbs the nav height through its ownmin-height: 100vh. - Asymmetry is banned. Hero content is center-aligned. Feature and team grids are center-aligned within their containers. This is a deliberate choice to reinforce editorial composure.
Elevation is whisper-quiet. The brand does not use bold drop shadows, neumorphism, or layered chrome. Three shadow tiers only:
- shadow-soft —
0 4px 6px -1px rgba(0,0,0,0.05), 0 2px 4px -1px rgba(0,0,0,0.03). Default for cards at rest. - shadow-hover —
0 20px 25px -5px rgba(0,0,0,0.08), 0 10px 10px -5px rgba(0,0,0,0.04)plustransform: translateY(-2px). Applied on hover for features and the CTA card only. - No shadow — Nav, buttons, chips, step numbers. Depth here is conveyed through 1px borders, not shadows.
In dark mode, soften the shadow alpha (0.2 / 0.1) and lean more on border
and surface contrast for separation. Glassmorphism (backdrop-filter: blur(10px)
with rgba(255,255,255,0.1)) is permitted only on the fixed navigation.
- Corners scale with scale:
sm (4px)for chips,md (8px)for buttons and inputs,lg (12px)for feature/content cards,xl (16px)for the CTA container. - The step-number circle and all pill chips use
rounded.full. - Geometric icons are the one place shape carries meaning. The six competency cards each own a distinct primitive — diamond, triangle, circle, hexagon, star, and a 4-rhombus "data-mesh" composition — drawn as 100×100 SVGs filled with their category gradient. The icon is the card's visual anchor; never combine it with a photograph or additional illustration.
- Avoid decorative strokes, dashed borders, inner shadows, or textured fills. If a surface needs visual interest, use the dotted hero pattern at 2.5% opacity — nothing else.
Two variants, always rectangular with rounded.md corners.
- Primary — Deep ink (
#111827) with white text. Default CTA. Hover lifts to#1F2937. In dark mode the background shifts toaccent #6366F1. - Secondary — White background,
border 1px border-color, gray-700 text. Used as the lower-priority sibling of a primary CTA. - Size: 48px tall for marketing pages, 40px for inline/sm variants. Horizontal
padding is
32px(md) /16px(sm). Never use full-width buttons on desktop. - Icons inside buttons are 20×20 (
w-5 h-5), withmargin-left: 8pxwhen trailing, and should translate+4pxon hover when the button implies forward motion (e.g. "Book a consultation").
- Feature card — white surface, 1px
border-colorborder,rounded.lg,padding: 32px. Hover reveals a 4px gradient underline at the bottom edge that scales from 0 to 100% width (transform-origin: left). The card itself lifts-2pxand swaps toshadow-hover. - Team card — 256px-tall gradient portrait with initials placeholder (until
real photography is supplied), hover-reveals a "View profile" pill. The
portrait applies
filter: grayscale(1)at rest and transitions tograyscale(0)on group hover over 500ms. - CTA card — white/glass surface inside a
surface-subtlesection,rounded.xl,padding: 48px, with a central primary button. No border.
Fixed top bar. Left: wordmark (organization name in two weights — base
in font-weight: 300, suffix in font-weight: 400 with gradient
text-clip). Center: 4 section links in body-md with hover lifting
color to primary. Right: a primary "Contact" button plus a theme
toggle. Collapses to a hamburger below 768px.
A vertical rail: 64px-diameter numbered circle on a 2px vertical line
(border-color). Each step stacks an h3 title, a body-lg description, and
a wrapping row of deliverable chips. Steps are spaced by 48px vertically and
the rail hides below 768px (number circles remain).
Three-column grid. Each stat is a centered stat-display number over a
label-caps label in secondary. Minimum gap: 32px. Never decorate stats
with icons, sparklines, or dividers — the restraint is the point.
A pill-shaped "Featured Insight" chip above the display headline. Background
surface-muted, body-sm text, arrow glyph (→) separating the eyebrow from
the linked teaser. Hover lifts background to #E5E7EB.
Do
- Reserve the accent gradient for 1–2 words per heading and the
-labhalf of the wordmark. - Use
font-weight: 300on every heading ≥24px. Resist the urge to bold. - Alternate
surfaceandsurface-subtleto pace long pages. Keep vertical rhythm atpy-24. - Lead every major section with an H1 + subtitle + short body intro, centered, max-width ≤ 48rem.
- Draw placeholder portraits with gradient + initials when real photography is unavailable. Keep the grayscale-on-rest, color-on-hover pattern.
- Animate opacity and transform only. Duration
300ms, easingease-out.
Don't
- Never apply the accent gradient to body copy, borders, buttons, or large surfaces. It loses meaning when repeated.
- Never mix a second typeface. Inter is the system; hierarchy comes from weight and size.
- Never use colored section backgrounds, neon accents, or saturated brand colors for non-decorative UI. The accent gradient is the only color event.
- Never stack shadows, add inner glows, or use
box-shadowblur radii above25px. Elevation whispers. - Never right-align or stagger section content. Editorial composure depends on centered layouts.
- Never pair the geometric icon with a photograph, emoji, or second illustration inside the same card. One visual anchor per card.
- Never animate color transitions — only
transformandopacity. This is locked in the stylesheet to prevent dark-mode flicker.
This is a token-level design-system manifest in the
Google Labs DESIGN.md format (alpha):
YAML front matter holds machine-readable tokens (version, name,
description, colors, typography, rounded, spacing, components);
the markdown body holds the rationale. Tokens are normative exact values;
prose explains when and why to apply them.
Section order is fixed. Prose sections may be omitted but must appear in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Duplicate headings are a hard error.
Token naming conventions
- Colors: surfaces
surface[-subtle|-muted], texton-*, accentaccent[-from|-to|-secondary], icon gradientsfeature-<hue>-from/-to, dark-mode counterparts prefixeddark-. - Typography:
display,h1–h4,body-{xl,lg,md,sm},label-caps,stat-display,button,code. Thelarge = lightrule (≥24px →fontWeight: 300) is the core brand constraint — prose must change with it. - Components: lowercase kebab-case; states as sibling entries
(
button-primary,button-primary-hover), one recipe per visual state.
Adding a token. Never hand-pick brand colors in consuming code. If a
token is missing, add it to the design that owns it first (this file, or the
identity/designs/<id>.md the work resolves to), then reference it. New colors go into
colors: (with a dark- counterpart for surface/text tokens) and get a
mention with role + contrast note in the Colors prose. Components reference
tokens via {colors.*} / {typography.*} — never raw hex in components:.
Renames must update all references in the same commit.
Consumers. Skills and agents that emit HTML, PDF, slides, certificates, dashboards, or styled emails read their palette, typography, and spacing from this file instead of inventing them. Keep copies in sibling UI-generating repos byte-identical — one source commit updates them all.
Change discipline. One tone — factual: each change is a small, described
commit (e.g. tokens(colors): tighten accent-from); lint with
npx @google/design.md lint DESIGN.md before committing; on a spec version
bump, update version:, re-lint, and diff against the previous revision.