Implement UI
Designimplement_uiImplement UI is an Agent Skill for design published in the Simon-Initiative/oli-torus repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Convert a provided UI design source into an implementation-ready design brief that maps visual intent to Torus design tokens, icons, reusable components, and code targets. Use when a Jira ticket or developer provides Figma or another design reference and the team needs governed implementation guidance before coding. Supports durable feature briefs and lightweight ticket-level briefs.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Simon-Initiative/oli-torus/blob/HEAD/.agents/skills/implement_ui/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/implement-ui, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Required Resources
Always load before running:
references/workflow.mdreferences/repo_waypoints.mdreferences/guardrails.mdreferences/target_organization.mdreferences/design_system_sources.mdassets/templates/ui_implementation_brief_template.md
Load when needed:
references/icon_mapping.md- when the brief needs to map a new icon, verify whether an icon already exists, or recommend icon-system extension
references/fidelity_rules.md- when the brief must describe static vs dynamic fidelity, overflow handling, or implementation constraints that affect layout matching
references/responsive_validation.md- when the design includes breakpoint-specific behavior, dense dashboards, charts, stacked layouts, or any responsive ambiguity that should be called out before coding
When running in feature mode, also read:
<feature_dir>/prd.md<feature_dir>/fdd.mdwhen present<feature_dir>/plan.mdwhen present
When the feature lives under an epic, also consult relevant epic docs under docs/exec-plans/current/epics/<epic_slug>/.
Mission
This skill does not implement UI code directly.
It produces an implementation-ready design brief that:
- identifies the visual source of truth
- maps design to existing Torus design tokens, icons, and reusable components
- identifies gaps that need developer confirmation
- recommends where code should live
Use it as a bridge between design references and the repo-local UI workflow, which then feeds implementation skills such as harness-develop or harness-work.
In this repository, when a Figma-backed UI task needs implementation fidelity and iterative comparison against the current UI, this skill should be treated as the governed brief-generation phase inside the repo-local ui_workflow skill documented at .agents/ui-workflow/README.md, not as the full workflow by itself.
Preferred Execution Context
This skill can run in plain Codex mode.
Prefer Tidewave when available for:
- complex UI surfaces
- responsive layouts
- dashboard or chart-heavy views
- work where visual fidelity is especially important
Why:
- Tidewave enables faster runtime inspection, viewport resizing, and visual verification against the design source.
- In practice this often produces a stronger brief with fewer hidden assumptions than Codex-only execution.
If Tidewave is not available, continue in Codex and record uncertainty more explicitly in Open Questions / Requires Approval.
Modes
Choose one mode up front:
-
full- Use for feature work that already has a spec pack.
- Write a durable artifact to
<feature_dir>/design/<slice_slug>.md. - This mode is appropriate when the design materially affects planning or slice-level implementation.
-
lightweight- Use for
harness-worktickets or smaller UI changes. - Produce the brief in chat by default.
- Do not create a file unless the user explicitly asks to persist the brief.
- Use for
If the request does not specify a mode:
- prefer
fullwhenfeature_diris provided - otherwise prefer
lightweight
Workflow
-
Resolve the source of truth for the design.
- Prefer explicit Figma links from the user.
- If the user points to a Jira ticket, extract Figma links from the ticket or its comments.
- If multiple Figma nodes exist, identify which nodes correspond to the scope being implemented.
- For icons, first check the Torus design-system icon source at
https://www.figma.com/design/4pTqLuqHbALAbZ31wvIHIX/NG-23---Torus-Design-System?node-id=2-24.
-
Classify the implementation surface.
liveview/heexreactmixed- State the chosen surface explicitly.
-
Inventory the design.
- layout and structure
- typography
- colors and semantic intent
- iconography
- interactive states
- responsive behavior
- ambiguities or missing states
-
Map the design to the existing system.
- design tokens
- icon system
- existing reusable components or patterns
- likely target modules/files
- whether the result should stay feature-local or be extracted to
design_tokens/ - for cross-feature primitives, first check whether a shared primitive already exists under
design_tokens/ - if proposing a new shared primitive, state where it should live, how it should appear in
/dev/design_tokens, and which Figma node should be linked from the catalog - load conditional references when icon extraction, fidelity rules, or responsive behavior need deeper guidance
-
Detect and record gaps.
- unrecognized token usage
- hardcoded colors with no clear token mapping
- missing icons
- reusable component candidates
- missing or ambiguous design states
-
Produce the design brief.
- Use the exact section blocks from
assets/templates/ui_implementation_brief_template.md. - In
fullmode, write<feature_dir>/design/<slice_slug>.md. - In
lightweightmode, return the brief in chat unless the user explicitly requests persistence.
- Use the exact section blocks from
-
End with a clear handoff.
- If implementation should follow, state whether the next skill should be
harness-developorharness-work. - Do not proceed to coding unless the user explicitly asks.
- If implementation should follow, state whether the next skill should be
Output Contract
Every brief must include:
Design SourcesImplementation SurfaceDesign System AlignmentToken MappingIcon MappingComponent Reuse PlanFile TargetsOpen Questions / Requires Approval
In lightweight mode, keep the same structure in chat unless the user asks for a shorter summary.
Guardrails
Follow the detailed rules in:
references/guardrails.mdreferences/target_organization.mdreferences/design_system_sources.mdreferences/icon_mapping.mdwhen icon work is in scopereferences/fidelity_rules.mdwhen fidelity or overflow behavior must be specifiedreferences/responsive_validation.mdwhen responsive behavior must be assessed
Non-negotiable rules:
- Prefer existing design tokens, icons, and reusable components before proposing new ones.
- For cross-feature primitives such as buttons, icon buttons, badges, pills, tabs, and simple feedback surfaces, prefer
design_tokens/over feature-local styling unless there is a clear reason to keep the work local. - If a new shared primitive is recommended, the brief must say that it should be wired into
/dev/design_tokensand linked to its canonical Figma source when one exists. - If a token, icon, interaction, or responsive behavior is ambiguous, record it under
Open Questions / Requires Approval. - Do not invent missing design behavior.
- Do not create or modify design tokens automatically. Recommend additions only when necessary and only with explicit approval.
Validation
Before finishing, verify that the brief:
- uses the exact section structure from
assets/templates/ui_implementation_brief_template.md - names the primary design source and the relevant Figma node ids or links
- states the implementation surface explicitly
- maps tokens, icons, reusable components, and file targets
- explicitly says whether any new primitive should live under
design_tokens/or remain feature-local - includes
/dev/design_tokensand Figma-link expectations when a new shared primitive is proposed - records any unresolved ambiguity or approval-dependent decision in
Open Questions / Requires Approval
Handoff Guidance
If the user wants implementation next:
- route the work through the repo-local UI workflow documented at
.agents/ui-workflow/README.md - use
harness-developfor planned feature execution after the workflow establishes the canonical brief and UI implementation path - use
harness-workfor smaller ticket-level execution after the workflow establishes the canonical brief and UI implementation path - tell the implementer to read the resulting brief before coding