Design Skills & Guardrails System

Introduction

Dais had adopted shadcn's default component library along with a Figma-connected MCP integration for Claude Code. The MCP read component structure and existing styles reliably at the atom and molecule level. The failure showed up one layer up: at the organism, template, and page level, where shadcn's default tokens, structural placeholders rather than semantic definitions, gave Claude Code nothing to resolve against. It started inferring semantics from visual proximity instead of an explicit mapping.

The Goal

Build a token and skill file system that gives Claude Code, and the engineers working alongside it, unambiguous semantic ground truth across product, marketing, and PoC surfaces, without requiring a human to manually review every AI-generated output to catch drift.

The Challenge

This is a coordination problem that gets worse, not better, with AI-assisted development. Traditional design drift happens slowly, one engineer's judgment call at a time. AI-generated drift happens instantly and at volume: a model without a defined system will confidently invent one, differently, every time it's asked. As the sole product designer covering three surfaces at once, the fix had to be structural rather than supervisory.

The Process

Four stages: research how other teams were solving the same class of problem, redesign the token architecture itself rather than patch shadcn's defaults, build and validate one skill file per surface in a sandboxed environment, then document and roll out.

The Research

Before rebuilding the token system, David studied how other AI-forward companies, particularly ones using AI to iterate on design in code or run automated A/B testing, structured their design tokens in shipped, publicly inspectable code. Not to copy their systems, but to understand what a token architecture looks like once a team has had to make it work under AI-driven iteration rather than only human designers hand-authoring components.

The pattern across nearly all of them: they'd gone a step further than shadcn's defaults by defining real component-level semantics, purpose-mapped tokens rather than raw structural placeholders. But almost none had simplified that layer. Most still defined state and style semantics per component rather than sharing them across components that played the same functional role. That gap, correct in principle but not simplified in practice, is what shaped the decision to build shared, universal component semantics into the Product UI skill file.

The Approach

The fix was rebuilding the semantic layer using the W3C Design Tokens format. Every semantic token carries an explicit alias reference back to a specific primitive variable, so a new template being generated for the first time had the same semantic ground truth as a component that had already been built.

The System

Three skill files, one per surface, each with its own token constraints and component state logic, built on the shared primitive and semantic foundation.

PoC Skills

PoC skills

Constrained tokens, simplified guardrails

Product UI Skills

Product UI skills

Shared component state logic

Marketing UI Skills

Marketing UI skills

Shared component state logic

PoC Skill File

Stakeholders in demos would fixate on visual polish rather than workflow logic. A reduced grayscale palette, single radius, and simplified state model structurally prevented high-fidelity output, so the constraint was a ceiling, not a suggestion.

Product UI Skill File

Shared component state logic. The semantic layer was restructured so state changes are defined once and inherited across components sharing a functional role, closing the drift gap the research surfaced in other companies' systems.

Marketing UI Skill File

Shared component state logic, with more expressive range, larger type, broader color, gradients, without losing the component logic connecting it to product. Guardrails direct the model toward marketing-appropriate token choices rather than constraining toward simplicity.

Validation Methodology

No automated lint or CI check enforced this yet, so the validation loop was manual but repeatable: run a generation pass, inspect resolved output against the token structure, log mismaps, adjust, rerun. This cycled until output converged to roughly 99% correct token resolution.

Going Forward

Impact

The token restructuring and validation loop were built and validated solo, in a sandboxed repo branch, until output converged to near-total accuracy across the atom, molecule, and previously-undefined organism/template/page levels.

What David Learned

The next phase was bringing engineers directly into the testing loop, validating against real production usage before company-wide rollout. That phase hadn't started before a round of layoffs, which included several of the engineers who would have been part of that testing, ended the initiative.

Next Steps

Building and validating a system solo gave David real confidence that it worked the way it was designed to. It didn't tell him how it survives contact with people who didn't build it. Not every system gets to finish its intended validation cycle, and knowing precisely what that next phase should have been is itself part of the work.

Want to know more about David Rivas? You can also check out Battery Trader or Sole Lucky.