Skip to content

Instantly share code, notes, and snippets.

@julrich
Created March 19, 2026 22:15
Show Gist options
  • Select an option

  • Save julrich/b36c3d4091879996721555e1540d31ae to your computer and use it in GitHub Desktop.

Select an option

Save julrich/b36c3d4091879996721555e1540d31ae to your computer and use it in GitHub Desktop.
DESIGN.md

DESIGN.md

Overview

A modern, professional design system for a content-rich corporate website built with kickstartDS. The visual language balances clean professionalism with a distinct teal-green brand identity. The design favors generous whitespace, clear typographic hierarchy, and subtle depth through shadows and border radiuses. Accessibility and responsive scaling are first-class concerns — typography, spacing, and layout all scale fluidly across breakpoints using a factor-based token system.

The overall feel is confident and structured, with a 3-tier token architecture (branding → semantic → component) that ensures consistency at every level while remaining fully themeable.

Colors

  • Primary (#007e6f): CTAs, primary buttons, active navigation, links, key interactive elements
  • On Primary (#ffffff): Text and icons placed on primary-colored backgrounds
  • Background (#ffffff): Default page background, surfaces, content areas
  • Background Inverted (#151515): Dark sections, inverted content blocks, footer
  • Foreground (#151515): Default body text, headings, primary content color
  • Foreground Inverted (#ffffff): Text on dark/inverted backgrounds
  • Link (#007e6f): Inline text links, navigation links
  • Positive (#23831b): Success states, confirmation messages, positive indicators
  • Negative (#ff1a57): Error states, destructive actions, validation errors
  • Informative (#64c2db): Info banners, tooltips, informational badges
  • Notice (#64c2db): Notices, alerts, attention-drawing elements

Color Scale

The design system generates 9 intermediate tints/shades from each base color using a non-linear scale:

Step Opacity/Mix Usage
1 95% Subtle hover states
2 90% Light interactive states
3 81% Secondary surfaces
4 68% Borders, dividers
5 50% Muted accents
6 32% Background tints
7 19% Faint backgrounds
8 10% Card backgrounds, accent surfaces
9 5% Near-transparent washes

Typography

  • Display Font: Inter — used for hero headlines, display-level text, and large visual headings
  • Copy Font: Inter — used for body text, paragraphs, and long-form content
  • Interface Font: Inter — used for buttons, labels, navigation, form elements, and UI controls
  • Mono Font: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace — used for code snippets and technical content

Font Sizes

Role Base Size Scale Factor
Display 20px grow: 1.5, shrink: 1.5, breakpoint: 1.5
Copy 16px grow: 1.5, shrink: 1.5, breakpoint: 1.5
Interface 16px grow: 1.5, shrink: 1.5, breakpoint: 1.5
Mono 16px grow: 1.5, shrink: 1.5, breakpoint: 1.5

Each font role uses a 7-step scale (xxs → xxl) generated by applying the grow/shrink factors to the base size. Sizes scale responsively across breakpoints using the breakpoint factor.

Font Weights

Name Value Usage
Light 300 Decorative display text, pull quotes
Regular 400 Body text, default weight
Medium 500 Subheadlines, emphasized labels
Semi-Bold 600 Headlines (h1–h4), navigation items
Bold 700 Strong emphasis, highlighted subheadlines

Headlines use the display font family with semi-bold weight. Subheadlines use the copy font family with bold weight. Body text uses regular weight. Interface elements (buttons, labels) use the interface font at the appropriate scale step.

Spacing

  • Base Unit: 18px
  • Scale Factor: 1.58 — each step multiplies the previous by this ratio
  • Grow Factor: 1.48 — controls upward scaling for larger sizes
  • Shrink Factor: 1.42 — controls downward scaling for smaller sizes
  • Breakpoint Factor: 1.5 — spacing grows proportionally across breakpoints

The spacing system generates a 7-step scale (xxs → xxl) from the base value. Spacing tokens are split into stack (vertical) and inline (horizontal) variants to support directional intent.

Elevation

This design uses shadows to convey depth and hierarchy. Shadow intensity is controlled by three factor tokens:

  • Blur Factor: 1 — standard blur radius (no amplification)
  • Opacity Factor: 1 — standard shadow opacity (no amplification)
  • Spread Factor: 1.5 — slightly amplified spread for broader, softer shadows

Shadows are applied to elevated UI elements like cards, flyout menus, headers, and modals. The system defines 5 shadow levels that progressively increase blur, spread, and offset. Components such as Hero textboxes, navigation flyouts, and teaser cards use elevation to separate interactive surfaces from the page background.

Border Radius

  • Radius Factor: 1.8 — produces generously rounded corners throughout the UI
  • Border Width: 1px — default border width for inputs, cards, and dividers

The radius factor is applied to computed base values, resulting in noticeably rounded but not pill-shaped corners. This gives the design a modern, approachable feel.

Components

The design system includes 46 component token sets with 730 component-level tokens across 9 categories:

Core UI (Forms)

  • Buttons: Three variants — Primary (solid brand fill #007e6f, white text), Secondary (interface background, default text), Tertiary (transparent background, bordered). Three sizes (small, medium, large) using interface font scale. All variants include hover and active states via semantic interactive color tokens.
  • Text Fields: 1px border, focus/hover/error border states, padding, label and placeholder styling, shadow on focus
  • Text Areas: Same styling system as text fields, with resizable container
  • Select Fields: Dropdown with border states, label, placeholder, and focus shadow
  • Checkboxes: Custom-styled with checked/hover/focus states, border-radius, and label alignment
  • Radio Buttons: Custom-styled with selected/hover/focus states and label alignment

Heroes & CTAs (3 components)

  • Hero: Full-width banner with textbox overlay, backdrop filter, gradient overlays, responsive min-height, and box shadow. Headline inherits from the Headline component tokens.
  • Video Curtain: Video background hero with textbox, overlay gradients, and responsive headline sizing
  • CTA: Call-to-action section with headline, copy, optional image, color variants, and generous padding

Cards (3 components)

  • Teaser Card: Image with hover scale (1.05), topic label, copy, and button. Uses card background color tokens. Has compact variant and hover transition effects.
  • Business Card: Contact card with avatar, image (configurable aspect ratio), border-radius, and structured contact info layout
  • Contact: Contact info card with image, title, copy, linked items, and flexible basis layout

Content (5 components)

  • Headline: h1–h4 levels with display font family, configurable letter-spacing, text-transform, and subheadline (copy font, bold weight, muted color). Includes highlight variant with custom background and optional anchor links.
  • Text: Text block with highlight variant and multi-column support
  • Rich Text: Rich text block with headline/body styling and vertical spacing
  • Image Text: Image-text block with standard and highlight variants
  • Image Story: Storytelling layout with copy, horizontal/vertical padding

Layout (4 components)

  • Section: The primary layout container with configurable column counts, gutters (small/default/large), content widths (narrow/default/wide/full/max), and three background modes (default, accent, bold). Includes slider integration and responsive breakpoint overrides.
  • Split Even: Equal-column layout with configurable gutters and sticky support
  • Split Weighted: Main/aside weighted layout with flexible basis ratios
  • Gallery: Image gallery with tile sizing and aspect ratio control (landscape, square, wide)

Data Display (6 components)

  • Features: Feature list with icons, titles, copy, and links. Multiple size variants with size multipliers.
  • FAQ: Accordion with expand/collapse, summary/answer styling, border separators
  • Stats: Statistics display with icon, number, topic, and copy
  • Testimonials: Quote display with source attribution, byline, image, and decorative quote icon
  • Downloads: File download list with hover states, icons, and structured item headers
  • Logos: Logo grid with responsive column count and tagline

Navigation (6 components)

  • Header: Page header with logo, floating variant, backdrop filter, responsive spacing, and shadow
  • Nav Topbar: Top navigation bar with label styling, icons, transitions, and floating variant
  • Nav Flyout: Flyout submenu with shadow, transitions, dimmed states, and max-width constraint
  • Nav Toggle: Hamburger menu toggle with floating variant
  • Breadcrumb: Breadcrumb navigation with icon separators
  • Pagination: Page navigation with active state, border-radius, and responsive border

Utility (5 components)

  • Footer: Page footer with logo, byline, navigation links, background color, and border-top
  • Cookie Consent: Banner/dialog with toggles, overlay, responsive padding, and box shadow
  • Slider: Content slider with arrow/bullet navigation, animation duration control
  • Lightbox: Overlay with counter, buttons, placeholder background
  • Divider: Visual separator with accent variant

Do's and Don'ts

  • Do use the primary color (#007e6f) only for the single most important action or element per view
  • Don't use raw color hex values in components — always reference semantic tokens (--ks-background-color-*, --ks-text-color-*)
  • Do maintain the 3-tier token hierarchy: branding → semantic → component. Component tokens should reference semantic tokens, not branding tokens directly.
  • Don't hardcode spacing values — use the spacing scale tokens (--ks-spacing-{stack,inline}-{xxs..xxl})
  • Do use the display font family for headlines and the copy font family for body text — never mix their roles
  • Don't use more than two font weights on a single screen section
  • Do preserve the border-radius factor of 1.8 for a consistent rounded feel across all components
  • Don't create flat/sharp corners that conflict with the established rounded aesthetic
  • Do use inverted color tokens (*-inverted) for content on dark backgrounds rather than manually overriding colors
  • Don't bypass the component token layer — if a component has dedicated tokens (e.g., --dsa-button_primary--*), use them instead of generic semantic tokens
  • Do leverage the responsive scaling system (grow/shrink/breakpoint factors) instead of writing manual media queries for font sizes and spacing
  • Don't introduce new shadow values — use the existing 5-level box-shadow scale governed by blur, opacity, and spread factors
  • Do ensure WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text) — the primary color #007e6f on white provides ~4.7:1
  • Don't use the primary color for large text blocks — it's designed for interactive elements and accents
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment