Skip to content

Latest commit

 

History

History
615 lines (535 loc) · 24.8 KB

DESIGN.md

File metadata and controls

615 lines (535 loc) · 24.8 KB
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
primary secondary surface surface-subtle surface-muted on-primary on-surface on-surface-muted border border-subtle accent-from accent-to accent accent-secondary feature-purple-from feature-purple-to feature-blue-from feature-blue-to feature-orange-from feature-orange-to feature-pink-from feature-pink-to feature-indigo-from feature-indigo-to success info attention dark-surface dark-surface-subtle dark-surface-muted dark-on-surface dark-on-surface-muted dark-secondary dark-border dark-accent-from dark-accent-to
#111827
#6B7280
#FFFFFF
#F9FAFB
#F3F4F6
#FFFFFF
#374151
#6B7280
#E5E7EB
#F3F4F6
#667EEA
#764BA2
#6366F1
#8B5CF6
#9333EA
#4F46E5
#2563EB
#0891B2
#EA580C
#DC2626
#9333EA
#DB2777
#4F46E5
#9333EA
#10B981
#3B82F6
#8B5CF6
#111827
#1F2937
#374151
#D1D5DB
#9CA3AF
#9CA3AF
#374151
#A78BFA
#818CF8
typography
display h1 h2 h3 h4 body-xl body-lg body-md body-sm label-caps stat-display button code
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
72px
300
1.05
-0.02em
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
48px
300
1.1
-0.02em
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
36px
300
1.15
-0.01em
fontFamily fontSize fontWeight lineHeight
Inter
24px
500
1.3
fontFamily fontSize fontWeight lineHeight
Inter
20px
500
1.4
fontFamily fontSize fontWeight lineHeight
Inter
20px
300
1.6
fontFamily fontSize fontWeight lineHeight
Inter
18px
400
1.6
fontFamily fontSize fontWeight lineHeight
Inter
16px
400
1.6
fontFamily fontSize fontWeight lineHeight
Inter
14px
400
1.5
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
14px
500
1.2
0.05em
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
36px
300
1
-0.02em
fontFamily fontSize fontWeight lineHeight
Inter
16px
500
1.25
fontFamily fontSize fontWeight
SF Mono, Monaco, Cascadia Code, Roboto Mono, Consolas, monospace
14px
400
rounded
none sm md lg xl full
0px
4px
8px
12px
16px
9999px
spacing
xs sm md lg xl 2xl 3xl 4xl 5xl
4px
8px
16px
24px
32px
48px
64px
96px
128px
components
button-primary button-primary-hover button-secondary button-secondary-hover nav-bar nav-link nav-link-hover card-feature card-feature-hover card-cta badge-featured chip-deliverable step-number input-text
backgroundColor textColor typography rounded padding
{colors.primary}
{colors.on-primary}
{typography.button}
{rounded.md}
16px 32px
backgroundColor
#1F2937
backgroundColor textColor typography rounded padding
{colors.surface}
{colors.on-surface}
{typography.button}
{rounded.md}
16px 32px
backgroundColor
{colors.surface-subtle}
backgroundColor textColor height padding
{colors.surface}
{colors.on-surface}
80px
0px 24px
textColor typography
{colors.on-surface-muted}
{typography.body-md}
textColor
{colors.primary}
backgroundColor textColor rounded padding
{colors.surface}
{colors.on-surface}
{rounded.lg}
32px
backgroundColor
{colors.surface}
backgroundColor textColor rounded padding
{colors.surface}
{colors.on-surface}
{rounded.xl}
48px
backgroundColor textColor typography rounded padding
{colors.surface-muted}
{colors.on-surface}
{typography.body-sm}
{rounded.full}
8px 16px
backgroundColor textColor typography rounded padding
{colors.surface}
{colors.on-surface}
{typography.body-sm}
{rounded.full}
4px 12px
backgroundColor textColor rounded size
{colors.surface}
{colors.primary}
{rounded.full}
64px
backgroundColor textColor rounded padding
{colors.surface}
{colors.primary}
{rounded.md}
12px 16px
site
stylesheet fonts colors colorsDark
docs/assets/brand.css
display body
Playfair Display
Inter
ink muted surface surface-subtle surface-muted on-surface line line-subtle accent-from accent-to accent accent-secondary ok info accent-text accent-soft ok-text info-text attention-text code-bg feature-indigo-from feature-indigo-to stage-surface stage-raised stage-line stage-link stage-hi stage-core stage-dust
#0F2A4A
#475569
#FAF7F3
#FFFFFF
#F1F5F9
#1A2433
#E2E8F0
#F1F5F9
#2D5B8F
#2D5B8F
#2D5B8F
#5FA0D9
#2D7A5F
#2D5B8F
#2D5B8F
#E6F0FA
#2D7A5F
#2D5B8F
#2D5B8F
#F1F5F9
#2D5B8F
#2D5B8F
#FAF7F3
#FFFFFF
#94A3B8
#2D5B8F
#5FA0D9
#E6F0FA
#E2E8F0
ink muted surface surface-subtle surface-muted on-surface line line-subtle accent-from accent-to accent accent-secondary ok info accent-text accent-soft ok-text info-text attention-text code-bg feature-indigo-from feature-indigo-to stage-surface stage-raised stage-line stage-link stage-hi stage-core stage-dust
#E7EAEE
#A8B1BD
#101419
#191E24
#20252C
#E7EAEE
#333E4C
#20252C
#5FA0D9
#5FA0D9
#5690D2
#5FA0D9
#43A37B
#5690D2
#5FA0D9
#182A40
#43A37B
#5FA0D9
#5FA0D9
#191E24
#5690D2
#5690D2
#101419
#191E24
#345373
#5690D2
#5FA0D9
#182A40
#333E4C

Designs in this Bridge

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/

Overview

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: 300 on 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–80rem wrappers. Edge-to-edge layouts are reserved for the hero only.

Colors

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 with surface-subtle #F9FAFB for 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 via background-clip: text to 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.

Dark mode

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.

Accessibility

  • 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.

Site layer

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/.

Typography

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-face with the woff2 bundled or referenced relative to the page), or fall back to the system stack Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, Roboto, sans-serif (San Francisco on macOS is the closest cousin). No fonts.googleapis.com / fonts.gstatic.com links, 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.6 is mandatory.
  • Stat-display (36px/300) — KPIs. Pair with a 14px uppercase label-caps underneath 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.

Layout

  • Container: max-width: 80rem (1280px) with padding-inline: 24px. Centered. Hero content narrows further to max-width: 64rem (5xl).
  • Section rhythm: vertical padding is always 96px top and bottom (py-24). Never less. Alternate surface and surface-subtle backgrounds 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 own min-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 & Depth

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) plus transform: 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.

Shapes

  • 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.

Components

Buttons

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 to accent #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), with margin-left: 8px when trailing, and should translate +4px on hover when the button implies forward motion (e.g. "Book a consultation").

Cards

  • Feature card — white surface, 1px border-color border, 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 -2px and swaps to shadow-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 to grayscale(0) on group hover over 500ms.
  • CTA card — white/glass surface inside a surface-subtle section, rounded.xl, padding: 48px, with a central primary button. No border.

Navigation

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.

Process timeline

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).

Stat blocks

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.

Hero badge

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's and Don'ts

Do

  • Reserve the accent gradient for 1–2 words per heading and the -lab half of the wordmark.
  • Use font-weight: 300 on every heading ≥24px. Resist the urge to bold.
  • Alternate surface and surface-subtle to pace long pages. Keep vertical rhythm at py-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, easing ease-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-shadow blur radii above 25px. 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 transform and opacity. This is locked in the stylesheet to prevent dark-mode flicker.

Maintaining this file

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], text on-*, accent accent[-from|-to|-secondary], icon gradients feature-<hue>-from/-to, dark-mode counterparts prefixed dark-.
  • Typography: display, h1–h4, body-{xl,lg,md,sm}, label-caps, stat-display, button, code. The large = light rule (≥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.