Skip to content

Samsen Internal Framework

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

Context Engineering vs. Vibe Coding

The Distinction

Two fundamentally different approaches to working with AI coding tools have emerged:

Vibe coding is improvisational. You describe what you want in loose terms, accept what the AI generates, and keep prompting until it looks right. There's no structured context, no spec, no systematic approach. You're vibing with the tool.

Context engineering is intentional. You prepare structured context — specs, token definitions, architectural patterns, examples — and feed it to the AI so it can generate output that matches your existing system precisely. You're engineering the context that produces reliable output.

Why This Matters

Vibe coding works for demos, prototypes, and throwaway experiments. It fails at production. The gap between "looks right in a demo" and "ships to a real codebase" is enormous, and that gap is made of context:

  • Does the generated code use your design tokens or hardcoded values?
  • Does it follow your component architecture or invent its own?
  • Does it match your naming conventions?
  • Does it work with your build system?
  • Does it respect your accessibility patterns?

Without context, AI guesses. With context, AI follows the system.

Context Engineering in Practice

Providing Design System Context

The most critical context for AI-assisted design is the design system:

  • Token definitions — Complete mapping of spacing, color, typography, elevation, and animation tokens. Both the Figma variable names and their CSS custom property equivalents.
  • Component patterns — How existing components are structured. File conventions, prop patterns, composition approaches.
  • Naming conventions — How things are named in the codebase. BEM, utility classes, CSS modules, whatever the project uses.

Providing Architectural Context

Beyond the design system, AI needs to understand:

  • File structure — Where components live, how they're organized, where tests go.
  • Dependencies — What libraries are available, what patterns they enforce.
  • Build constraints — What the bundler expects, what transforms are applied.

The CLAUDE.md Pattern

The most effective way to provide persistent context to Claude Code is through a CLAUDE.md file at the repo root. This file contains:

  • Project overview and architecture
  • Key conventions and patterns
  • Design system token reference
  • Common commands (build, test, lint)
  • Things to avoid

Claude Code reads this file automatically, giving it baseline context for every interaction.

See: ../claude-code/project-setup.md

The Spectrum

Context engineering isn't binary. It's a spectrum:

Level Context Provided Output Quality Use Case
No context (pure vibe) Just a prompt Unpredictable Quick experiments
Light context Design system name, rough description Approximate Early prototypes
Moderate context Token file, component examples Good Internal tools, MVPs
Full context Complete spec, token mapping, architecture docs, CLAUDE.md Production-ready Shipping to real codebases

The Samsen methodology operates at the "full context" end. This is what enables designers to ship to production — the context does the heavy lifting that would otherwise require developer expertise.

Common Vibe Coding Failures

These patterns indicate vibe coding that will fail in production:

  • Hardcoded values — padding: 16px instead of padding: var(--spacing-md). Works in the demo, breaks the system.
  • Invented components — AI creates a modal from scratch instead of using the existing modal component. Duplicates code, diverges from patterns.
  • Framework mismatch — AI generates React class components when the codebase uses hooks. Or uses a CSS library that isn't in the project.
  • Accessibility gaps — Without context about a11y patterns, AI produces visually correct but semantically broken markup.
  • Inconsistent naming — Files, classes, and props don't match existing conventions. Code review becomes a battle.

The Samsen Position

Vibe coding is fine for learning and exploration. But for professional practice — for shipping — context engineering is non-negotiable. The investment in preparing structured context pays for itself on the first component, and compounds with every subsequent one.

This is why design system alignment is so central to the Shipping AI Designer framework. The design system is the context. When it's properly structured and documented, it becomes the bridge that turns vibe coding into context engineering automatically.