Nexa Design System · Component Documentation
Component Definition Matrix
A structured reference for documenting each component beyond its visual appearance — capturing purpose, usage, constraints, variants, states, behaviour, accessibility, decision logic, token dependencies and the context AI needs to interpret it correctly.
How this was used: The matrix acted as the documentation framework for the component-definition phase. Each component was defined against the same set of questions so its detail page could communicate both design intent and the rules behind its use.
01
Component Definition Matrix
{len(data)} components · {len(headers)} definition fields
| Component | Purpose | When to use | Don't use when | Variants | States | Behavior | Accessibility | Decision Logic | Token Dependencies | Content Rules | MVP Constraints | AI Interpretation | Similar Components / Differentiator |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Select | Lets users choose one option from a predefined set. | Use when choices are known and one value must be selected. | Don't use for free-text entry, multiple independent selections, or navigation. | Single select; searchable select where justified. | Default, hover, focus, open, selected, disabled, read-only, error. | Opens options; keyboard navigation; selection closes the list. | Visible focus; keyboard operable; accessible label; selected state announced. | Choose Select for one-of-many predefined values. | Surface, text, border, focus, status, elevation, spacing. | Label identifies field; placeholder describes expected choice. | Keep multi-select and complex cascading behavior out of MVP. | AI should choose it from decision type and option set, not visual preference. | Distinguish from Search Field, Menu, and future radio/segmented controls. |
| Tab | Switches between peer-level views within the same context. | Use for mutually exclusive peer views that share the same conceptual context. | Don't use for primary navigation, sequential steps, or unrelated actions. | Default/active; optional count badge. | Default, hover, active, focus, disabled. | Selecting a tab changes associated content while preserving context. | Keyboard navigation; clear selected state; visible focus; accessible labels. | Use Tab for peer views, not destination navigation. | Action/accent, text, surface, border, focus. | Labels should be concise, parallel, and distinguish views. | Avoid nested/complex/scrolling tabs in MVP. | AI should use Tab when choosing between peer content views. | Distinguish from Navigation Item and segmented controls. |
| Count Badge | Communicates a small numeric count associated with an object, category, or state. | Use when a compact count adds context to an existing label or control. | Don't use when the number is the primary data point or needs detailed explanation. | Numeric count; compact count if supported. | Default; contextual/active; disabled if needed. | Displays a count; not an independent action. | Do not rely on color alone; meaning should be clear. | Use as supporting metadata, not standalone status or action. | Surface, text, action/accent, spacing. | Keep values short; define overflow convention if needed. | No interactive badge behavior in MVP. | AI should treat it as metadata attached to another element. | Distinguish from Status/Status Chip: quantity vs condition. |
| Avatar | Represents a person or identity in compact visual form. | Use for person, assignee, author, owner, or participant. | Don't use for objects, categories, or generic markers. | Image; initials/monogram; fallback. | Default; fallback; selected/active only when required. | Displays identity and may pair with name/role/status. | Meaningful accessible name for known person; decorative avatars should not be redundant. | Choose based on identity representation, not shape. | Avatar surface, text, spacing, status. | Initials are fallback when no usable image exists. | No avatar groups/presence systems unless required. | AI should use Avatar only for identity/personhood. | Distinguish from icons and generic status markers. |
| Navigation Item | Moves users to a product destination or navigation section. | Use for persistent/contextual navigation between destinations. | Don't use when only changing content within the same context. | Default; active; disabled; icon; badge where supported. | Default, hover, active, focus, disabled. | Navigates to destination and communicates current location. | Keyboard accessible; current-location state; visible focus. | Use when interaction changes product location. | Surface, text, action/accent, border, focus. | Concise destination names; consistent hierarchy. | No mega-navigation or complex nested navigation in MVP. | AI should interpret it as destination-changing control. | Tab = peer view; Navigation Item = destination; Menu Item = contextual option. |
| Breadcrumb | Shows hierarchical location within the product. | Use when users benefit from understanding or moving upward through hierarchy. | Don't use for shallow/obvious hierarchy. | Single-line hierarchy; truncated hierarchy if supported. | Default; current item; focus/hover on linked ancestors. | Ancestor items navigate upward; current page is not itself a link. | Navigation landmark semantics; current page distinguished. | Use for hierarchy, not primary navigation or back buttons. | Text, action/accent, spacing, icon, focus. | Use actual hierarchy names; concise labels; clear current location. | Avoid complex truncation/responsive transformations in MVP. | AI should choose it when hierarchy itself is useful context. | Distinguish from Navigation Item and Back action. |
| Label and Value Field | Presents a structured attribute and its corresponding value. | Use for read-oriented record details, metadata, and structured information. | Don't use for editing or content better suited to tables/paragraphs. | Single label/value; grouped metadata. | Default; emphasized value; unavailable/empty where needed. | Primarily informational; does not imply editing. | Clear programmatic label/value relationship; preserve reading order. | Use when presenting an attribute/value relationship. | Text primary/secondary/tertiary, spacing, surface. | Labels concise; values retain domain meaning and units. | No inline editing in MVP. | AI should use it for structured read-only information. | Distinguish from input fields: communicate vs collect/edit. |
| Menu | Presents contextual actions or choices in a temporary surface. | Use when related options should be revealed on demand. | Don't use for primary navigation, always-visible choices, or direct primary actions. | Action menu; option menu where supported. | Closed, open, item hover/focus, selected, disabled, destructive. | Opens from trigger; keyboard navigation; closes after selection/dismissal. | Appropriate menu semantics; keyboard navigation; focus management. | Use for contextual choices/actions revealed on demand. | Surface, elevation, text, border, action, status, spacing. | Group related actions; verbs for actions; explicit destructive actions. | No deep nesting/submenus in MVP. | AI should select Menu when options are contextual and hidden until requested. | Distinguish from Navigation Item and Select. |
| Tooltip | Provides brief supplementary information about an unfamiliar or ambiguous element. | Use when concise explanation helps without persistent UI. | Don't use for essential information, substantial content, or inaccessible touch-only content. | Informational; control explanation. | Hidden, visible, focus-visible. | Appears on hover/focus and dismisses when trigger is no longer active. | Available on keyboard focus; never hide essential information only in tooltip. | Use for supplementary explanation, not critical instructions. | Inverted surface, text on inverted, elevation, spacing. | Brief and specific; explain unfamiliar controls rather than repeat labels. | No rich/interactive tooltip panels in MVP. | AI should treat it as secondary explanatory content. | Distinguish from inline help, error messaging, and persistent guidance. |
| Toast | Provides transient feedback about a completed, failed, or noteworthy system event. | Use for brief feedback that does not need persistent visibility. | Don't use for critical decisions, persistent information, or field-level errors. | Success, warning, error, informational where supported. | Visible; dismissing; timed dismissal where appropriate. | Appears temporarily; auto/manual dismissal based on importance. | Appropriate live-region behavior; avoid overwhelming assistive technology. | Use only when feedback can safely disappear. | Status, inverted surface, text on inverted, elevation, spacing. | State what happened and useful next action; avoid vague messages. | No notification-center orchestration in MVP. | AI should choose Toast only for safely transient feedback. | Distinguish from inline errors/status and persistent banners. |
| Empty State | Explains why a content area has no content and may provide a next action. | Use when a meaningful content region is empty and explanation/action is useful. | Don't use when absence is self-explanatory or loading is appropriate. | First-use; no results; no items; unavailable/permission if required. | Context-specific empty condition; action available/unavailable. | Explains condition and may provide relevant next action. | Clear heading/explanation; accessible action; illustration not sole carrier of meaning. | Use when emptiness is a meaningful product state. | Surface, text, action, illustration/icon, spacing, status. | State what is empty, why it matters, and what can be done next. | Avoid elaborate illustrations or multiple competing actions in MVP. | AI should use it when absence of content needs explanation or recovery. | Distinguish from loading, error, and generic placeholder states. |
02
Claude Prompt Guide
Rules used when translating matrix definitions into component detail pages
PurposeUse this matrix as the source of truth for component semantics, behavior, constraints, and AI decision logic.
StructureFollow the established component-detail page structure used by Primary Button, Icon Button, Search Field, and Tab.
ConsistencyPreserve the existing visual language, page hierarchy, tab treatment, and card patterns. Do not redesign the framework.
AccuracyDo not invent variants, states, behaviors, token relationships, or governance rules not supported by this matrix or the existing system.
AI lensMake decision logic explicit enough for AI to choose a component from intent and context rather than visual similarity.
MVPPrioritize the minimum viable definition. Do not add chatbot interfaces, speculative governance, or enhancement features.
WorkflowBuild one component at a time, test it, and update this matrix when a decision changes.