Skip to content

Samsen Internal Framework

This is Samsen's internal framework content for Design Systems. It is read-only reference material.

Context-Based Design Systems (CBDS)

The Framework

Context-Based Design Systems (CBDS) is a Southleft framework that extends traditional design system thinking by making context explicit and machine-readable. The core idea: components should know about and respond to the context in which they're used, and this context should be documented in a way that both humans and AI can consume.

The Problem CBDS Solves

Traditional design systems define components in isolation: "here's a button, here are its variants." But in practice, components behave differently depending on where they appear:

  • A button in a modal has different spacing constraints than a button in a form
  • A card in a dashboard grid has different content rules than a card in a marketing page
  • A heading in a sidebar has different typography than a heading in the main content area

Designers carry this contextual knowledge in their heads. Developers learn it through experience or bug reports. AI has no way to access it at all — unless you make it explicit.

CBDS makes context a first-class citizen of the design system.

CBDS Structure

Each component in a CBDS has three documentation layers:

1. Component Definition (Standard)

The traditional design system documentation: variants, props, tokens, accessibility requirements. This is what most design systems already have.

2. Context Rules

Explicit documentation of how the component behaves in different contexts:

## Button — Context Rules

### In Modal Footer
- Always right-aligned
- Primary action on the right, secondary on the left
- Minimum width: 120px
- Uses spacing-md gap between buttons

### In Form
- Full-width on mobile, auto-width on desktop
- Submit button always uses action-primary variant
- Disabled state required until form validates

### In Card Actions
- Ghost variant preferred
- Maximum 2 actions visible, overflow to menu
- Icon-only on mobile breakpoint

3. AI Context Block

A structured block specifically designed for AI consumption:

## Button — AI Context

When generating a Button:
- Check the parent container type (modal, form, card, page)
- Apply the context rules for that container
- If the container type is not documented, use the default variant
- Never generate a button without a clear action label
- Always include an aria-label if the button is icon-only
- The token for button background is --button-color-bg, not --color-action-primary directly

Why Context Matters for AI

Without context rules, when you ask Claude Code to "add a save button to this modal," it has to guess:

  • Where should it be positioned?
  • What variant should it use?
  • What spacing applies?
  • Should there be a cancel button next to it?

With CBDS, the AI reads the context rules and applies them automatically. The output is consistent with design system conventions on the first try, because the conventions are documented, not assumed.

CBDS and Token Architecture

CBDS extends the token architecture with context-scoped tokens:

/* Standard component tokens */
--button-padding-x: var(--spacing-16);

/* Context-scoped tokens */
--modal-footer-button-min-width: 120px;
--modal-footer-button-gap: var(--spacing-md);
--card-action-button-variant: ghost;

This creates a hierarchy: global tokens → component tokens → context-scoped tokens. Each layer narrows the decision space, making AI output more predictable.

Implementing CBDS

Step 1: Audit Existing Context Knowledge

Most design teams already have context rules — they're just undocumented. Common places this knowledge hides:

  • Designer memory ("we always do it this way")
  • Code comments ("// Note: in sidebar, use compact variant")
  • PR review feedback ("this should be right-aligned in modals")
  • Bug reports ("button spacing is wrong when used in a card")

Step 2: Document Context Rules Per Component

For each component, list the contexts it appears in and the rules that apply. Start with the most-used components: buttons, cards, inputs, headings, navigation items.

Step 3: Add AI Context Blocks

For each component, add a structured block that AI tools can consume directly. This block should be:

  • Imperative ("use X", "apply Y", "never do Z")
  • Specific (token names, exact values, concrete rules)
  • Concise (AI doesn't need rationale, just instructions)

Step 4: Integrate with CLAUDE.md

Reference the CBDS documentation in the project's CLAUDE.md file so Claude Code loads context rules automatically.

Relationship to Other Southleft Frameworks

  • Specs-first methodology — CBDS documentation follows specs-first: markdown source, generated views. The context rules are the spec.
  • Token architecture — CBDS extends the three-layer token model with a fourth context layer.
  • Hybrid workflow — Context rules help Figma ↔ code alignment by making implicit decisions explicit.