Start with three separate contracts
A reliable Codex UI task has three contracts. The source contract identifies the approved design decisions. The implementation contract defines what Codex may change and which consumer must adopt those decisions. The acceptance contract lists the conditions that must be observed before the work can pass.
Mixing those contracts creates false confidence. A DESIGN.md can say that cards use tonal separation instead of shadows, but it can't prove that a particular card follows the rule. A token file can contain the right light and dark values without proving that the application loaded it. One screenshot may show a correct card, but it can't establish the approved token or supported interaction behavior.
Delivery is not adoption
A successful file write, MCP response, package installation, build, or screenshot proves only that event. It doesn't prove that the intended source version reached every required consumer or behaved correctly under the stated conditions.
Give every decision one authoritative home. When two layers disagree, resolve the conflict at the earliest governing layer instead of accepting whichever value happens to render.
| Authority | What it governs | What it cannot prove | |
|---|---|---|---|
| Repository instructions | Repository instructions | Codex behavior, workflow, required checks, file scope, and project-specific constraints | That the visual system is complete or the rendered UI is correct |
| DESIGN.md | DESIGN.md | Visual intent, role definitions, layout guidance, motifs, and explicit prohibitions | Exact runtime values or correct component adoption |
| Token and framework artifacts | Token and framework artifacts | Exact reusable values, semantic roles, modes, and framework mappings they explicitly contain | That the project consumed the current artifact |
| Component contract | Component contract | Supported variants, states, structure, interaction behavior, and accessibility responsibilities | That every product instance uses the supported component correctly |
| Approved exception | Approved exception | One named deviation, its scope, owner, reason, and expiry or retest trigger | Permission for the same deviation elsewhere |
| Rendered observation | Rendered observation | What happened for one recorded consumer, version, environment, and condition | Design authority, untested conditions, or general accessibility conformance |
Use a simple conflict rule. Current repository instructions control how Codex performs the task. The approved design source controls intent, generated artifacts control the values they contain, and component contracts control reusable behavior. Narrowly approved exceptions override only their named scope. Observations never outrank these sources; they reveal whether the chain worked.
Keep instruction scope and design scope distinct
Codex repository instructions are the right place for commands, workflow requirements, ownership boundaries, and validation duties. They should point to the design source instead of duplicating the palette, spacing scale, or component rules in a second copy that slowly diverges. Current OpenAI documentation remains authoritative for how Codex discovers and scopes those instructions.
DESIGN.md has a different job. It explains the visual system in terms an agent can apply: semantic roles, typography, layout, component treatments, motifs, and prohibited moves. Keep exact values connected to machine-readable artifacts where possible. If the prose and a generated token artifact disagree, stop and identify the approved source version instead of asking Codex to improvise a compromise.
Choose the delivery route that matches the maintained source
The route should follow the source your team already maintains. Don't choose MCP merely because it's newer, or checked-in files merely because they're visible in the repository. Choose the route that can identify the source, preserve the required artifacts, and leave a reviewable handoff.
| Checked-in files | Identity Forge CLI or MCP | Figma MCP | |
|---|---|---|---|
| Best fit | The repository is the maintained handoff and changes need ordinary version review | The team wants a published kit delivered through agent tooling or applied as project artifacts | The maintained design context lives in Figma and the task needs a design-to-code or code-to-design round trip |
| Source identity to record | Commit or artifact version plus file paths | Kit slug and version plus delivered artifact identities | Figma file, relevant component or variable source, and captured revision context |
| Downstream work | Map tokens, fonts, and rules into the project's actual stack and components | Inspect delivered files, select the matching framework route, and map consumers | Translate design components, variables, fonts, colors, and layouts into the implementation |
| Evidence limit | Presence in Git does not prove runtime consumption | Connection, retrieval, or generation does not prove correct application adoption | Retrieved Figma context or an editable round trip does not prove production behavior |
Identity Forge's CLI can configure its MCP server for Codex and verify the connection. That check is useful but narrow: it shows that the configured route responds. The project still owns placement, dependency compatibility, local mappings, component behavior, exceptions, accessibility evaluation, and runtime acceptance.
Figma MCP fits when Figma is part of the real authority chain. OpenAI documents both bringing design context into Codex and turning implemented UI into editable Figma designs. The round trip can help collaboration, but the returned design or code remains a proposal until the appropriate owner accepts it and verifies the named consumer.
Inspect a real source before choosing the route
Use a published kit to inspect the guidance and token roles Codex would receive. Then decide whether your project should check them in or retrieve them through agent tooling.
Freeze the source contract before prompting
Record the source contract before Codex touches the consumer. At minimum, name the system and version, available artifacts, supported modes, typography roles, layout rules, protected decisions, exclusions, unresolved fields, and the person or role that owns acceptance. An unresolved decision should stay unresolved. Don't let the model silently turn it into policy.
- Source identity: system name, version, retrieval date, and owner.
- Artifact inventory: the exact guidance and machine-readable outputs supplied to the task.
- Supported scope: modes, viewports, components, states, and content conditions covered by the source.
- Protected rules: decisions Codex may implement but may not reinterpret.
- Exclusions: product behavior, routes, components, or files outside the task.
- Unresolved fields: decisions that still require an owner rather than model judgment.
- Acceptance owner: the person or role permitted to choose accept, revise, or block.
Bounded intake: Ambient Sage v1
Ambient Sage v1 works as an intake example because its public kit page identifies a concrete system rather than a loose mood. It uses a warm-sage canvas, tonal card separation without shadows or borders, a single vivid yellow accent, Plus Jakarta Sans for heading and body roles, and JetBrains Mono for technical strings. The public kit has semantic light and dark tokens and six artifact routes: DESIGN.md, DTCG, CSS, Tailwind v3, Tailwind v4, and shadcn.
Token specimen · real values
Ambient Sage
Live renderAmbient Sage's actual tokens — the same values its exports use.
That inventory establishes upstream availability. It doesn't establish implementation in a particular repository. At intake, keep the Codex project paths, framework mapping, font loading, component adoption, accessibility results, runtime compatibility, and rendered observations marked unresolved. They become claims only when the receiving project records evidence.
Available, implemented, observed
Available means the source can provide the artifact. Implemented means the project maps or consumes it. Observed means someone recorded what a named consumer did under stated conditions. Keep the three states separate.
Give Codex one bounded implementation task
The task below is illustrative and unexecuted. It shows the precision needed for a dashboard summary-card consumer without claiming that Codex, Ambient Sage, or a particular framework produced a tested result.
task_id: dashboard-summary-card-ambient-sage-v1
status: illustrative_unexecuted
source:
kit: ambient-sage
version: v1
required_artifacts:
- DESIGN.md
- matching semantic token artifact for the project's stack
consumer:
name: dashboard-summary-card
version: unresolved
scope:
viewports:
- narrow: 390px
- wide: 1440px
modes:
- light
- dark
content_cases:
- short label and ordinary value
- long label without clipping
- empty value with approved fallback copy
interaction_cases:
- keyboard focus on the card action
- disabled action if the component contract supports it
protected_surfaces:
- dashboard navigation
- unrelated cards
- global typography outside the named consumer
exclusions:
- data-fetching behavior
- route changes
- new component variants
- claims of accessibility conformance
required_evidence:
- delivered artifact identity
- local token and font mapping
- component contract and version
- rendered captures for each required viewport and mode
- keyboard observation for the supported action
- diff confirming protected surfaces did not change
acceptance_rule: withhold acceptance until every required observation has a recorded dispositionThe task names a consumer instead of asking Codex to "apply the design system." It also separates source facts from project decisions. Ambient Sage supplies the upstream intent and artifacts. The receiving project must decide where those files belong, how semantic roles map into its stack, which component contract applies, and how to observe each required condition.
Record expectations before observations
Write the expected result first. Otherwise, a plausible render can quietly redefine the requirement. Each verification case should cover one consumer version and one meaningful condition. Several cases may point to the same screenshot or test log, but every disposition should remain independently reviewable.
handoff_id: codex-ui-YYYY-MM-DD-01
source:
name: Ambient Sage
version: v1
owner: design-system-owner
delivered_artifacts:
- identity: DESIGN.md
version_or_hash: unresolved
- identity: project-token-artifact
version_or_hash: unresolved
project_mapping:
repository_revision: unresolved
token_entrypoint: unresolved
font_entrypoint: unresolved
local_exceptions: []
verification_cases:
- case_id: summary-card-wide-light-long-label
consumer: dashboard-summary-card
consumer_version: unresolved
viewport: 1440px
mode: light
content_condition: long label
interaction_condition: default
environment: unresolved
expectation: Uses approved semantic roles and preserves the full label without overlap or clipping.
observation: NOT_RECORDED
evidence_reference: NOT_RECORDED
first_divergent_layer: NOT_ASSESSED
correction_owner: UNASSIGNED
retest_trigger: Any source, artifact, mapping, component, font, or layout change affecting this case.
disposition: block
acceptance_owner: product-ui-owner
final_disposition: blockA blank observation isn't an interface failure. It's missing evidence. Use block when that evidence is required for the stated scope, revise when a known mismatch has an owner and correction path, and accept only after every required case has an observation that matches its expectation or a properly approved exception.
Verification cases worth recording
- Artifact delivery: the named source version produced or supplied the expected files.
- Project mapping: the application loads the intended token, typography, and mode entrypoints.
- Component adoption: the named consumer uses the supported component and variant rather than a detached copy.
- Responsive behavior: the consumer works at each required viewport, including content extremes.
- Mode behavior: semantic roles remain correct in every supported visual mode.
- Interaction behavior: supported hover, focus, disabled, error, and keyboard conditions match the component contract.
- Protected surfaces: unrelated consumers named in the task remain unchanged.
- Rendered result: captures or observations identify the repository revision, consumer version, environment, and condition.
Accessibility evaluation belongs in this record when required, but don't fold it into visual approval. A correct palette, token mapping, or screenshot doesn't prove keyboard operation, zoom resilience, assistive-technology behavior, or accessibility conformance. Record the evaluation method and conditions separately.
Diagnose the first divergence, not the ugliest symptom
When the result drifts, trace the chain in ownership order. The first divergence is the earliest point where the recorded expectation and inspected state stop matching. Fixing a later symptom can hide the problem while leaving every other consumer exposed.
- 1
Check the source policy
Confirm that the intended rule is explicit, approved, current, and owned. If the source is ambiguous, return the decision to its owner.
- 2
Check the delivered artifact
Confirm that the expected source version produced the artifact Codex received. Look for stale, partial, or mismatched outputs.
- 3
Check the project mapping
Inspect how the application loads and aliases tokens, fonts, modes, and framework values. A correct source can fail during this translation.
- 4
Check the component contract
Verify that the named consumer uses the supported component, variant, structure, and state behavior.
- 5
Check approved exceptions
Determine whether a local difference is deliberate, scoped, owned, and still valid. An undocumented override isn't an exception.
- 6
Check the rendered consumer
Record the actual result under the required viewport, mode, content, interaction, and environment conditions.
Assign the correction only after locating that point. A source owner resolves unclear intent. The delivery owner regenerates a stale artifact, while the application owner fixes a mapping. The component owner corrects reusable behavior. The consumer owner removes an unauthorized local override. This keeps Codex from compensating in the wrong layer.
Retest from the changed layer downward
If the source changes, regenerate and retest the entire required chain. If only one consumer mapping changes, retest that mapping, its component behavior, named protected surfaces, and rendered cases. The retest boundary should match the reach of the change.
Make the acceptance decision explicit
Accept when the source and artifacts are identified, every required mapping and consumer is traceable, observations cover the promised conditions, protected surfaces remain stable, and each exception is approved within a narrow scope. Choose revise when the first divergence is understood and has a bounded correction. Choose block when required evidence is missing, authority is unresolved, the wrong source version was delivered, or a material condition contradicts the contract.
This process doesn't benchmark every Codex delivery route or guarantee compatibility with a framework. Nor does it make Identity Forge the owner of project behavior. Identity Forge can supply the upstream kit and delivery mechanisms. The consuming project owns placement, mapping, component behavior, local exceptions, runtime compatibility, accessibility evaluation, observations, and final acceptance.
Start with one traceable consumer
Choose a published design kit and deliver the matching guidance and artifact. Complete one source-to-render record before expanding the system to more screens.
Sources
- Custom instructions with AGENTS.md: OpenAI documents repository instruction discovery for Codex, making scoped instruction files the appropriate authority for agent behavior and workflow constraints.
- Designing delightful frontends with GPT-5.4: OpenAI recommends defining typography, color, layout, and product constraints before frontend implementation, then reviewing the resulting hierarchy and visual anchor.
- Building frontend UIs with Codex and Figma: OpenAI documents a Codex and Figma MCP workflow involving design-system components, variables, fonts, colors, and layout changes.
- OpenAI Codex and Figma launch seamless code-to-design experience: OpenAI describes Figma MCP as a route for bringing design context into Codex and moving implemented UI back into editable Figma designs.
- Introducing Codex: OpenAI's historical launch article describes reviewable evidence such as logs and tests while warning that generated code still requires human validation; the page itself is marked outdated.
- Product Design and UI With OpenAI Codex: OpenDesign presents a detailed Codex UI workflow built around a brief, design constraints, desktop and mobile conditions, interaction requirements, and review before handoff.
- Ambient Sage Design Kit: The public Ambient Sage v1 kit provides DESIGN.md and implementation artifacts, semantic light and dark tokens, Plus Jakarta Sans typography, and JetBrains Mono for technical strings.
- Identity Forge changelog: Identity Forge states that its CLI can configure the Identity Forge MCP server for Codex and verify the connection with its doctor command.