Skip to content

Samsen Internal Framework

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

Specs-First Methodology

The Principle

Markdown is the source of truth. Everything else — HTML views, rendered documentation, generated artifacts — is a derived output. If there's ever a conflict between the markdown source and a generated artifact, the markdown wins.

This is more than a file format preference. It's a methodology for how knowledge, specifications, and documentation should flow through a project.

The Workflow

1. Create or modify the markdown source of truth
       ↓
2. Generate artifacts (HTML, PDF, components) for review or consumption
       ↓
3. Never commit generated artifacts to the repo

Why Markdown as Source

  • Diffable — Markdown produces clean, readable diffs in git. You can see exactly what changed in a spec, who changed it, and when.
  • AI-friendly — Claude Code and other AI tools work natively with markdown. It's the lingua franca of AI-assisted development.
  • Portable — Markdown renders everywhere: GitHub, VS Code, documentation sites, Notion imports. No vendor lock-in.
  • Composable — You can include, reference, and link between markdown files. A spec can reference another spec. Knowledge builds on knowledge.
  • Lightweight — No build step required to read or edit. Any text editor works.

Why Not Commit Generated Artifacts

Generated artifacts (HTML views, compiled docs, etc.) create merge conflicts, bloat repos, and introduce a second source of truth. If someone edits the HTML directly instead of the markdown, the sources diverge and trust breaks down.

The rule: generate on demand, never persist.

Specs-First in Practice

For Documentation

Instead of writing documentation after the fact, write the specification first. The spec is the documentation. When implementation follows the spec and the spec is kept current, documentation is never stale.

Pattern: 1. Write the spec in markdown (what should exist, how it should behave, what tokens it uses) 2. Implement from the spec (Claude Code reads the spec as context) 3. Update the spec when requirements change (the spec is the single mutation point)

For Design System Components

Each component has a markdown spec that defines: - Variants and states - Token usage (spacing, color, typography) - Responsive behavior - Accessibility requirements - Edge cases

Claude Code reads this spec and implements accordingly. When the spec changes, Claude Code can re-implement. The spec is the contract.

For Content

Content specifications define: - Target audience - Key claim / thesis - Evidence / proof points - Voice and tone constraints - Format requirements

Content is then generated or written against the spec. The spec ensures consistency across multiple pieces, multiple authors, or multiple AI sessions.

Dual-Format Pattern

For stakeholder-facing documentation, a dual-format pattern works well:

  1. Markdown source — The canonical version. Lives in the repo. Gets versioned, diffed, reviewed.
  2. HTML artifact — Generated on demand for visual review. Includes styling, navigation, table of contents. Never committed.

This pattern is validated by how major design systems handle their documentation: IBM Carbon, GitHub Primer, Stripe, GitLab, and Figma all maintain markdown or structured data as source, with generated documentation sites as the view layer.

See: ../../research/documentation-architecture.md

Connection to AI-Assisted Workflows

Specs-first is particularly powerful with AI tools because:

  • Context injection — You can feed a spec directly to Claude Code as context. "Here's the spec for this component. Implement it."
  • Validation — You can ask Claude Code to compare implementation against spec. "Does this component match the spec?"
  • Iteration — When you update the spec, you can re-run implementation. The spec is the stable reference point across iterations.
  • Consistency — Multiple AI sessions producing content or code from the same spec will produce consistent output, because the spec constrains the solution space.