The main prompts used to audit, normalize, structure and validate the foundation layer of the Nexa Design System.
Analyze the existing UI and identify reusable design elements, design debt, inconsistencies, missing tokens, and opportunities for standardization. Categorize findings into Foundations, Navigation, Inputs, Actions, Display, Identity, Feedback and identify whether each should become a Token, Primitive Component, Composite Component or Pattern.
Review the existing Foundation Library and refactor it into a designer-first Design System intended primarily for UX/UI designers working in Figma. Preserve all existing token values and design decisions, but improve how they are documented and presented. Replace implementation-oriented details (such as OKLCH values, CSS variables and engineering syntax) with designer-friendly documentation. For every colour token, present: Token Name, Light Theme (HEX + swatch), Dark Theme (HEX + swatch), Purpose, Recommended Usage, Avoid Using For, and UI Examples. Organize colours into categories such as Brand, Surface, Text, Border, Status and Interactive colours. Ensure every Light Theme token has a corresponding Dark Theme token, generating missing dark theme equivalents where necessary while maintaining accessibility and semantic consistency. Prioritize clarity, usability and visual examples over engineering implementation details.
The Foundation Tokens have now been finalized and organized under the Design Language section of the Pareo Design System. Before building reusable components, I want to establish an explicit Semantic Token layer that bridges the gap between Foundation Tokens and Components, following the same design methodology used in modern Figma Design Systems. Do not create any new visual styles or modify the existing Foundation Tokens. Instead, create a new documentation page under the Design Language section titled: Semantic Token Mapping This page should become the canonical reference that defines how every Foundation Token is consumed throughout the Design System. Objective Establish a clear dependency hierarchy: Foundation Tokens ↓ Semantic Tokens ↓ Components Components should reference Semantic Tokens, not Foundation Tokens directly. This relationship should be documented explicitly throughout the Design System. Build a Semantic Token Library Create semantic tokens that reference the existing Foundation Tokens. Do not duplicate HEX values, typography values, spacing values or other primitives. Every semantic token must map back to an existing Foundation Token. Organize semantic tokens into categories such as: Surface Surface / Primary Surface / Secondary Surface / Elevated Surface / Disabled Text Text / Primary Text / Secondary Text / Tertiary Text / Disabled Text / On Accent Action Action / Primary Action / Primary Hover Action / Secondary Action / Disabled Border Border / Default Border / Focus Border / Error Status Success Warning Error Info Icon Icon / Primary Icon / Secondary Icon / Disabled Expand these categories only if required by the current application. Build a Semantic Mapping Matrix On the same page, create a designer-friendly mapping matrix that clearly documents the relationships between tokens. The matrix should contain the following columns: Foundation TokenSemantic TokenUsed ByBrand / 500Action / PrimaryPrimary Button, Links, Active TabsGray / 900Text / PrimaryLabels, Table Cells, CardsGray / 100Surface / SecondaryCards, PanelsGray / 300Border / DefaultInputs, Cards Continue this matrix until every semantic token has a corresponding Foundation Token and documented usage. Theme Mapping Every semantic token should document: Light Theme Foundation Token Dark Theme Foundation Token Purpose Components that consume it If a corresponding Dark Theme mapping is missing, derive one using the existing Design Language while maintaining accessibility and semantic consistency. Future Component Integration This page should become the single source of truth for token relationships. When generating components in future iterations: Components should reference Semantic Tokens Components should never reference Foundation Tokens directly Multiple components sharing the same visual intent should reuse the same Semantic Token Documentation Style Present this documentation in a designer-first format similar to Figma Variables documentation. The page should help designers understand: Why semantic tokens exist How they relate to Foundation Tokens Which components consume them How changing a Foundation Token propagates through the Design System Use clear diagrams, tables and examples where appropriate. This page should serve as the missing bridge between Design Language and Components, ensuring a scalable and maintainable Design System architecture.
Expand the existing Semantic Relationship Matrix in the Nexa Design System to include the relationship between Semantic Tokens and the existing Components. This is an extension of the existing relationship model. Do not rebuild or replace the current Foundation → Semantic relationships. Preserve everything that already exists. 1. Extend the relationship model The relationship model should now represent: Foundation → Semantic → Component → Property → State For example: Brand Accent → Action / Primary → Primary Button → Background → Default And: Brand Accent → Action / Primary → Primary Button → Background → Hover 2. Use only existing components Use the Component Inventory and existing component detail pages as the source of truth. Do not create new components. Do not include patterns yet. Only map components that have already been identified from My Inventory v2. 3. Map semantic tokens to component properties For each existing component, identify which semantic tokens control its relevant visual properties. Examples of properties may include: Background Text Icon Border Focus indicator Placeholder Selected state Disabled state Error state Elevation Only include properties that are actually relevant to that component. Do not create artificial mappings simply to complete the table. 4. Include component states Where states already exist in the component documentation or are visibly represented in My Inventory v2, map the semantic relationship for each state. Examples: Default Hover Focus Selected Disabled Error Loading If a state is not currently defined or observed, do not invent it. Mark it as Not defined where useful. 5. Preserve the existing semantic layer Components must reference the existing Semantic Tokens, not raw Foundation Token values. Do not: Create duplicate semantic tokens Rename semantic tokens Change token values Create new foundation tokens Replace the existing Foundation → Semantic relationship If a component currently uses a raw value and there is no appropriate semantic token, flag it as: Semantic mapping required Do not automatically invent a new semantic token. 6. Designer-friendly matrix Keep the matrix understandable to designers. Add or use columns such as: ComponentPropertyStateSemantic TokenDesign Intent Example: | Primary Button | Background | Default | Action / Primary | Primary interactive emphasis | | Primary Button | Label | Default | Text / On Accent | Text displayed on primary action | | Primary Button | Background | Hover | Action / Primary Hover | Indicates interactive hover state | | Primary Button | Focus | Focus | Border / Focus | Provides visible keyboard focus | Do not expose unnecessary engineering implementation details. 7. Maintain traceability Each relationship should be traceable through the existing system: Foundation ↓ Semantic Token ↓ Component ↓ Property ↓ State The existing Foundation → Semantic relationship should remain the authoritative source for how semantic tokens resolve to foundation values. The component layer should explain where and why the semantic token is consumed, not duplicate the foundation values. 8. Validation Before finalizing: Compare the mappings against the existing Component Inventory. Compare them against each component's existing detail page. Compare the semantic tokens against the existing Semantic Relationship Matrix. Identify any component properties currently using raw values instead of semantic tokens. Identify any semantic tokens that currently have no component usage. Identify any ambiguous or missing relationships. Do not resolve ambiguity by inventing new tokens or relationships. At the end, provide a concise summary of: Number of components mapped Number of semantic → component relationships identified Number of component states mapped Any unmapped properties Any semantic tokens currently unused by components Any relationships requiring design review Important: This is a relationship-mapping and audit exercise. Do not redesign components, modify the UI, create patterns, or change the existing token architecture.
I want to validate the token dependency model within the Pareo Design System. This is a verification exercise rather than a redesign. Update the following Foundation Token: Foundation Token Accent Current Values Light Theme #008E8E Dark Theme #00BEB7 Replace them with: Light Theme #0B74FF Dark Theme #4F8CFF After updating the Foundation Token: 1. Check whether every Semantic Token mapped to the Accent Foundation Token updates automatically. 2. Verify whether every component referencing those Semantic Tokens also reflects the updated colour. 3. Verify whether the application screens using those components update accordingly.
Create a new page under the existing Design Language section called Semantic Relationship Matrix. The purpose of this page is to document the current relationship between Foundation Tokens and Semantic Tokens in the Nexa Design System. Scope For this phase, document only: Foundation Token → Semantic Token → Design Intent Do not include components, patterns, screens, or other downstream relationships yet. Those will be added in a later phase once components have been created and validated. Build the matrix Review the existing Foundation Tokens and Semantic Token definitions already present in the Design System and create a clear mapping matrix. Use these columns: For each relationship: Reference the existing token names exactly as they are currently defined. Do not create new Foundation or Semantic Tokens. Do not rename existing tokens. Do not change token values. Clearly describe what design intent the semantic token represents. Include both Light and Dark theme values where applicable. If a semantic token does not currently have a clear Foundation relationship, flag it as Unmapped rather than inventing a relationship. If multiple semantic tokens derive from the same Foundation Token, show each relationship separately. Important distinction This page is not another Foundation Token documentation page. The Foundation Library explains what the foundational values are. The Semantic Token documentation explains what the semantic tokens mean. This matrix explains how the two layers are related. Designer-friendly presentation Keep the page easy for a designer to scan and understand. Avoid engineering terminology wherever possible. Use clear descriptions such as: Accent → Action / Primary → Primary interactive emphasis rather than implementation-focused descriptions. Do not over-engineer this This is the first version of the relationship model. Do not add: Component mappings Pattern mappings Screen mappings Code references Motion relationships Z-index / stacking relationships Engineering metadata Additional token categories Those relationships will be investigated later. Validation Before finalizing the page: Compare the matrix against the existing Foundation Tokens. Compare it against the existing Semantic Tokens. Ensure every documented relationship actually exists in the current Design System. Do not infer or invent relationships that aren't explicitly supported by the existing system. Preserve all existing pages, navigation, tokens, values, and documentation. This is a documentation and relationship-mapping exercise only. Do not modify the existing Design System architecture or token definitions
The goal is to reorganize the existing content into a tab-based navigation structure, following the same interaction pattern and visual treatment already established for the Primary Button and Tab Bar component detail pages. IMPORTANT: This is an information architecture change, not a redesign. Preserve the existing visual language, typography, cards, spacing, token content, and examples wherever possible. Do NOT introduce a chatbot, reasoning panel, AI assistant, or any new enhancement. ================================================== TAB STRUCTURE ================================================== Create three tabs directly below the Semantic Tokens page header: 1. Overview 2. Token Library 3. Mapping The tabs should use the same tab navigation pattern already established on the Primary Button and Tab Bar detail pages. ================================================== TAB 1 — OVERVIEW ================================================== Use this tab to explain the semantic token model. Keep the existing page introduction, but reorganize it into a concise overview. Include: - What semantic tokens are - Why they sit between foundation tokens and components - The one-way dependency model: Foundation Tokens ↓ Semantic Tokens ↓ Components Explain that: - Foundation tokens represent raw, context-free values. - Semantic tokens give those values an explicit design intent. - Components consume semantic tokens rather than directly referencing foundation values. - A semantic token can resolve differently by theme while preserving the same intent. Retain the existing "How to read a semantic token" section here. Keep the existing example: Action / Primary Hover and its: - Category - Role - Resolves To Also retain the high-level principles currently communicated on the page, such as: - One change, everywhere - Intent survives the value - Themes stop being a fork Do not invent additional principles. The Overview should be relatively short. It should explain the model, not repeat the entire token library. ================================================== TAB 2 — TOKEN LIBRARY ================================================== Move the existing semantic token category sections here. Preserve the existing categories and content exactly as currently defined. Organize them in the same order they currently appear: - Surface - Text - Action - Border - Status - Elevation - Any additional semantic categories already present on the page For each category, preserve: - Category description - Semantic token cards - Token name - Token variable name - Light value - Dark value - Purpose - Consumed By - Visual examples The individual token cards are important because they make semantic intent and usage explicit. Do not remove or consolidate token cards simply to make the page shorter. ================================================== TAB 3 — MAPPING ================================================== Move the existing "Semantic Mapping Matrix" section into this tab. This is NOT a separate "Semantic Relationship Matrix" page. The matrix should remain part of the Semantic Tokens documentation. Keep the existing columns: - Foundation Token - Semantic Token - Used By Preserve the existing rows and relationships. The purpose of this tab is to allow a designer or AI to trace the dependency chain: Foundation Token → Semantic Token → Component / Usage Add a short introductory sentence explaining that this matrix is the canonical reference for tracing how foundation values flow into semantic intent and ultimately into components. Do not create another relationship matrix elsewhere. ================================================== PAGE HEADER ================================================== Keep the existing page header: DESIGN LANGUAGE Semantic Tokens Retain the existing introductory positioning, but make it concise enough that the tab navigation can sit naturally below it. The header should establish: "Semantic tokens give raw foundation values a name, purpose and context that components can consume." Do not over-explain AI here. ================================================== NAVIGATION BEHAVIOUR ================================================== The three tabs should behave like the tabs already established on the Primary Button and Tab Bar detail pages. Requirements: - Only one tab's content is visible at a time. - Active tab has the existing design-system active treatment. - Switching tabs should preserve the page context. - The page should open on "Overview". - Do not create separate routes unless the existing component-detail implementation already uses routes for tabs. - Follow the existing implementation pattern rather than introducing a new tab system. ================================================== MVP CONSTRAINT ================================================== Do NOT add: - Chat interface - AI reasoning panel - Relationship graph - Separate governance page - Separate Semantic Relationship Matrix - AI explanation panel - Search/filter functionality - Additional token-management features The purpose of this change is simply to make the existing semantic-token documentation easier to navigate. The final information architecture should be: Semantic Tokens [ Overview ] [ Token Library ] [ Mapping ] Overview → Understand the semantic token model Token Library → Explore the actual semantic tokens Mapping → Trace Foundation → Semantic → Component relationships Keep everything else in the design system unchanged.