The Context Stack: Product Truth, Visual System, Surface Strategy
The hard part of directing an AI design agent is not choosing a color. It is deciding which facts the agent must preserve, which visual decisions should remain consistent, and which choices belong only to the surface in front of the user. Impeccable's context stack answers those questions through three authorities: PRODUCT.md for durable product truth, DESIGN.md for reusable visual decisions, and a surface brief for one route or artifact's strategy. Understanding that separation lets a reader decide where a new instruction belongs instead of adding another vague preference to the prompt.
PRODUCT.md answers what must remain true
Impeccable's init flow begins with product truth, not visual direction. It explores the repository, asks about material gaps, and records the people who use the product, the job they are doing, the product's purpose, its position, its operating context, its capabilities, its constraints, its evidence, and its accessibility requirements. Platform is part of that record too. The flow supports web, iOS, Android, and adaptive projects, because a native design language changes which later guidance applies.
The sequence is deliberate. A product record can say that the users are designers, product managers, and engineers working inside AI coding tools. It can say that success means steering generated interfaces with design precision and producing work that can withstand professional review. It can record that the project has no customer testimonials or quantified outcome studies, so later copy must not invent them. None of those facts chooses a visual world. They establish the reality that a visual world must serve.
That distinction prevents a common failure in AI-assisted design: treating visual invention as if it were product discovery. If an agent begins with a palette and a mood, it can produce a coherent page while silently changing the audience, exaggerating the evidence, or optimizing for a landing-page convention that does not fit the actual task. init therefore does not write DESIGN.md, select a hero composition, or decide whether the visitor should be persuaded, taught, or helped through an operation. It preserves the facts before asking the system to interpret them visually.
The boundary also changes how missing context is handled. A project without PRODUCT.md needs product discovery before a new surface or redesign. A narrow refinement of an existing interface may proceed from the code and assets, with initialization offered afterward. The difference is scope. A small correction can use the incumbent implementation as evidence. A new visual world needs confirmed product truth because it can otherwise turn an agent's first guess into an unreviewed product decision.
This is not merely a documentation preference. PRODUCT.md owns the questions that should survive a visual change. If a team later replaces a dark interface with a light one, the product's audience, purpose, evidence limits, and accessibility commitments should remain. If those facts sit only in the conversation that produced the first design, the next agent has no reliable way to know which parts are negotiable and which are not.
The record also creates a boundary around inference. Repository evidence can suggest that a project is a web product, that it contains a certain workflow, or that a design system already exists. It cannot, by itself, confirm an unspoken customer segment, a performance promise, or a testimonial. The init guidance therefore asks only about material gaps and allows undecided facts to remain open. That restraint is useful for AI work because a confident invented detail can steer every later visual choice. A blank field is visible uncertainty; a fabricated fact looks like authority.
DESIGN.md and the surface brief answer different visual questions
DESIGN.md begins where PRODUCT.md stops. It records the reusable visual system that agents should follow: colors, typography, layout, elevation and depth, shapes, components, and concrete do's and don'ts. Its YAML frontmatter is machine-readable. The body explains how the tokens behave and why they exist. An accompanying .impeccable/design.json sidecar can carry information that the frontmatter cannot, including tonal ramps, shadow and motion extensions, breakpoints, component snippets, and narrative rules.
The difference between a token and a rule matters. A token can say which gold is the primary accent or which radius belongs to a button. A named rule can say that the primary accent carries the brand while a secondary color is reserved for improvement or live state. An agent can apply the values mechanically, but it needs the rule to avoid spreading an accent everywhere simply because the token is available. The system therefore treats visual language as both data and interpretation.
The split also gives maintenance a place to land. If a button changes shape across the product, the team can ask whether a shared component or token is wrong, whether one surface has an intentional exception, or whether the visual system itself has changed. Without a normative visual record, every inconsistency looks like a fresh design decision. With one, drift becomes a question that can be routed to the right owner. That is the difference between a page that happens to look coherent and a system an agent can extend without guessing.
Impeccable's own DESIGN.md makes this visible. Its Neo Kinpaku system uses dark lacquer surfaces, kinpaku gold, verdigris patina, small radii, restrained borders, and a geometric sans voice. Those choices are evidence of this repository's current visual world, not universal Impeccable defaults. A different project might have a light paper system, a dense operational interface, or a visual language inherited from an existing product. The purpose of DESIGN.md is to preserve the chosen system, not to make every project resemble the repository.
The document flow also distinguishes scanning from seeding. When code, tokens, components, or rendered output already exist, document extracts what is actually there and asks the human to supply qualitative language that code cannot safely infer, such as a creative north star or the character of the component system. When no visual system exists, seed mode records a direction without pretending that implementation tokens already exist. In either case, the file is an authority only when it describes a confirmed or observed world.
A surface brief is narrower. It belongs to one route, feature, or artifact and holds the strategy that should not be promoted into a global design system. It can record the visitor's mode, the task or question, the proof or content the surface must carry, the relevant states and realistic ranges, the selected direction, the first viewport, the signature interaction, and unresolved decisions. This is where Impeccable places the fact that a particular page is a landing page meant to persuade, a dashboard meant to support repeated operations, or documentation meant to help a reader understand.
The four visitor modes make the boundary concrete. Persuade means that the visitor must decide and act. Operate means that the visitor must complete a task, so scanability and consistency usually matter more than spectacle. Read means that the visitor must understand something, which makes structure, measure, and wayfinding central. Experience means that the visitor is inside the work itself and the interface should recede enough for the artifact to lead. The same product can use different modes on different surfaces. A tool's marketing page is not an Operate surface simply because the product is a tool.
That distinction changes what counts as a good visual decision. On a Persuade surface, the first viewport may need to make the product's mechanism legible and earn a decision quickly. On an Operate surface, the same dramatic treatment could compete with the task, so consistency, state visibility, and familiar controls may carry more weight. On a Read surface, line length, heading rhythm, navigation, and progressive disclosure become part of the product's function. The design system supplies the vocabulary, but the surface brief decides which parts of that vocabulary must be loud, quiet, dense, or deferred.
The diagram is a map of ownership, not a claim that the files are independent silos. Commands read the resolved context together. A surface brief inherits product truth and visual authority while adding a local strategy. A direction contract can refer to the system without copying all its tokens. The point is to prevent two opposite mistakes: forcing a route-specific decision into the global system, or allowing a local experiment to ignore the product and visual authorities around it.
A missing document is therefore not a blank check. If a project has a coherent visual system in its CSS, components, assets, or rendered output but no DESIGN.md, Impeccable treats the implementation as incumbent evidence. Documentation can be added without replacing the world. If the request is an explicit redesign, the existing look becomes evidence and an anti-reference, while product truth and working behavior remain in force. This distinction protects teams from a subtle form of drift: replacing a real identity merely because its written description has not yet been created.
The repository's own documentation shows why this authority needs to be explicit. docs/CLI-CONTRACT.md identifies itself as a historical source snapshot and carries older package and registry counts, while the current skill source, command metadata, and Rust registry describe the present system. Those files should not be silently harmonized into one timeless statement. A reader or agent needs to know which artifact is current for which question. Context is not just accumulated information; it is information with ownership and freshness.
Consider a single product with a public landing page, an authenticated dashboard, and a guide for new users. PRODUCT.md can define the product's audience and the evidence it can honestly present. DESIGN.md can define the type scale, component states, color roles, and spacing language shared by all three. The landing page's brief can choose Persuade and require a first viewport that proves the product's mechanism. The dashboard's brief can choose Operate and prioritize dense, familiar task flow. The guide's brief can choose Read and prioritize explanatory sequence. None of these decisions contradicts the others because each layer owns a different question.
Mix the layers and the drift is predictable. Put a route's hero concept in DESIGN.md, and every future surface inherits a composition that was never meant to be global. Put the brand palette and component states only in a surface brief, and the next page will reinvent them. Put product claims in a visual document, and an agent may treat a decorative statement as verified evidence. Put everything in a single prompt, and the system loses the ability to tell an old truth from a new preference.
A useful test is to classify a new instruction by the kind of change it implies. “Our audience is internal analysts and the interface must work with keyboard navigation” belongs with product truth and accessibility. “Buttons use a compact radius and the primary action uses the documented accent” belongs with visual authority. “The report page must help an analyst compare two periods before exporting” belongs with the surface brief. “Try a denser first viewport for this report” belongs with the direction contract or a scoped revision. The same sentence can be valid in one layer and harmful in another if it is allowed to become a global rule without justification.
This classification also makes handoffs less lossy. A product manager can confirm the job and evidence without editing a token file. A designer can revise the visual system without rewriting the audience definition. An engineer can implement a surface-specific state without turning it into a universal component rule. An AI agent can then read the same distinctions instead of treating every nearby sentence as equally binding.
The context stack does not eliminate the need to choose. It makes the choice legible. Once product truth, visual authority, and surface strategy have a clear relationship, the next question becomes possible: given these constraints, which visual direction should the agent and the user commit to? That is where Impeccable moves from remembering the product to deciding how one surface should make the product understood.