Web App UI Component System Builder

Project name: NexaCore Web Application UI System

Product type: Multi-tenant B2B SaaS platform

Target users: Product designers Frontend developers Design-system maintainers QA engineers Product teams

Frontend stack: Next.js React TypeScript

Styling approach: Tailwind CSS with semantic CSS variables

Component foundation: shadcn/ui and Radix UI primitives

Documentation: Storybook

Testing: Vitest React Testing Library Playwright Visual regression testing

Design source: Partial Figma library Existing production interface Incomplete token documentation Several duplicated components

Accessibility target: WCAG 2.2 AA implementation review

Browser support: Current and previous major versions of Chrome, Safari, Firefox, and Edge

Theming: Light theme Dark theme Future white-label themes

Responsive targets: Desktop Tablet Mobile

Localization: English at launch Future multilingual support Allow approximately 30% text expansion Future RTL support

Required foundations: Color Typography Spacing Sizing Radii Borders Shadows Elevation Motion Breakpoints Grid Z-index Icon sizing

Required components: Button Icon Button Link Card Pricing Card Text Field Text Area Select Combobox Checkbox Radio Group Switch Date Picker Search Field File Upload Form Field Error Summary Header Sidebar Breadcrumbs Tabs Pagination Table Data Grid Alert Toast Badge Avatar Progress Skeleton Empty State Error State Modal Drawer Popover Tooltip Dropdown Menu Accordion Command Palette Step Indicator

Need output: Complete component system architecture Token structure Component inventory Component specifications Prop recommendations Variant and state matrices Responsive behavior Accessibility requirements Storybook story plan Testing strategy Naming conventions Contribution workflow Versioning and deprecation policy Migration plan Developer handoff Acceptance criteria QA checklist

Special constraints: Preserve existing shadcn/ui and Radix behavior where appropriate. Do not create unnecessary duplicate components. Clearly separate observed patterns from recommendations. Avoid framework lock-in in the conceptual documentation. Support light and dark themes. Include keyboard behavior and focus management.

=== WEB APP UI COMPONENT SYSTEM ===

Project: NexaCore Web Application UI System

System Type: Shared product design system and React component library

Primary Consumers:

• Product designers
• Frontend developers
• QA engineers
• Product teams
• Design-system maintainers

Implementation Context:

• Next.js
• React
• TypeScript
• Tailwind CSS
• Semantic CSS variables
• shadcn/ui
• Radix UI
• Storybook

=== EXECUTIVE SUMMARY ===

NexaCore should use a layered component-system model:

Layer 1: Primitive design tokens

Layer 2: Semantic tokens

Layer 3: Component tokens

Layer 4: Foundation and layout primitives

Layer 5: Reusable interface components

Layer 6: Product-specific composite components

Layer 7: Page templates and workflows

The system should preserve stable accessibility and interaction behavior from Radix primitives while standardizing visual styling, component APIs, responsive rules, testing, and documentation.

The existing interface contains duplicated button, card, input, alert, and modal patterns. These should be consolidated before new variants are introduced.

=== SYSTEM PRINCIPLES ===

1. Prefer composition over excessive configuration.
2. Use semantic tokens rather than hard-coded visual values.
3. Maintain consistent keyboard and focus behavior.
4. Keep component APIs predictable.
5. Avoid product-specific business logic inside foundational components.
6. Support light and dark themes.
7. Preserve accessibility semantics.
8. Document states, variants, and content constraints.
9. Treat responsive behavior as part of the component contract.
10. Introduce new components only when reuse is justified.

=== TOKEN ARCHITECTURE ===

Primitive Tokens:

• Raw colors
• Font sizes
• Font weights
• Spacing values
• Radius values
• Shadow values
• Motion durations
• Breakpoints

Semantic Tokens:

• Background
• Surface
• Text
• Border
• Action
• Focus
• Status
• Overlay
• Disabled
• Inverse

Component Tokens:

• Button backgrounds
• Input borders
• Card surfaces
• Alert colors
• Tooltip surfaces
• Table row states
• Modal overlays

Token Relationship Example:

Primitive: color.blue.600

Semantic: color.action.primary

Component: button.primary.background.default

=== COLOR TOKENS ===

Surface Tokens:

• color.background.page
• color.background.surface
• color.background.elevated
• color.background.subtle
• color.background.inverse

Text Tokens:

• color.text.primary
• color.text.secondary
• color.text.muted
• color.text.disabled
• color.text.inverse
• color.text.link

Border Tokens:

• color.border.default
• color.border.strong
• color.border.subtle
• color.border.focus
• color.border.error

Action Tokens:

• color.action.primary
• color.action.primary-hover
• color.action.primary-pressed
• color.action.secondary
• color.action.destructive

Status Tokens:

• color.status.success
• color.status.warning
• color.status.error
• color.status.info
• color.status.neutral

Accessibility Rule: Status must never be communicated by color alone.

=== TYPOGRAPHY TOKENS ===

Display:

• display.large
• display.medium
• display.small

Headings:

• heading.1
• heading.2
• heading.3
• heading.4

Body:

• body.large
• body.default
• body.small

Labels:

• label.large
• label.default
• label.small

Utility:

• caption
• overline
• code
• data.value
• table.header

Each style must define:

• Font family
• Weight
• Size
• Line height
• Letter spacing
• Text transform
• Intended use
• Responsive behavior
• Fallback

=== SPACING SCALE ===

Recommended Base: 4-pixel primitive scale

Tokens:

• space.0 = 0 px
• space.1 = 4 px
• space.2 = 8 px
• space.3 = 12 px
• space.4 = 16 px
• space.5 = 20 px
• space.6 = 24 px
• space.8 = 32 px
• space.10 = 40 px
• space.12 = 48 px
• space.16 = 64 px

Semantic Spacing:

• spacing.page.inline
• spacing.page.block
• spacing.section
• spacing.card
• spacing.form.field
• spacing.control.inline
• spacing.modal
• spacing.table.cell

=== RADIUS SYSTEM ===

• radius.none = 0 px
• radius.small = 4 px
• radius.control = 8 px
• radius.card = 12 px
• radius.panel = 16 px
• radius.round = 999 px

Usage:

• Controls use radius.control.
• Cards use radius.card.
• Large overlays use radius.panel.
• Circular and pill elements use radius.round.

=== ELEVATION SYSTEM ===

Elevation 0: Flat surfaces

Elevation 1: Cards and low-priority floating regions

Elevation 2: Popovers, dropdowns, and sticky surfaces

Elevation 3: Drawers and modal content

Elevation 4: Critical overlays only

Rules:

• Elevation should communicate layering.
• Dark-theme shadows require dedicated tuning.
• Borders may supplement shadows when contrast is insufficient.

=== MOTION TOKENS ===

Durations:

• motion.instant
• motion.fast
• motion.normal
• motion.slow

Easing:

• motion.ease.standard
• motion.ease.enter
• motion.ease.exit

Reduced Motion: Nonessential spatial animation must be removed or substantially reduced when the user prefers reduced motion.

=== BREAKPOINTS ===

Small: 0–639 px

Medium: 640–1023 px

Large: 1024–1439 px

Extra Large: 1440 px and above

Breakpoint Rule: Component behavior should be defined by content and interaction needs rather than device labels alone.

=== COMPONENT INVENTORY ===

Actions:

• Button
• IconButton
• Link
• SplitButton
• MenuButton

Surfaces:

• Card
• PricingCard
• Panel
• Divider

Forms:

• FormField
• TextField
• TextArea
• Select
• Combobox
• Checkbox
• RadioGroup
• Switch
• DatePicker
• DateRangePicker
• SearchField
• FileUpload
• ErrorSummary

Navigation:

• Header
• Sidebar
• Breadcrumbs
• Tabs
• Pagination
• CommandPalette

Data Display:

• Table
• DataGrid
• Badge
• Avatar
• Progress
• KeyValueList
• Timeline

Feedback:

• Alert
• Toast
• Skeleton
• Spinner
• EmptyState
• ErrorState
• PermissionState

Overlays:

• Modal
• Drawer
• Popover
• Tooltip
• DropdownMenu
• ConfirmationDialog

Disclosure:

• Accordion
• Collapsible

Progress:

• StepIndicator
• ProgressBar
• ProgressCircle

=== COMPONENT SPECIFICATION ===

Component: Button

Purpose: Initiate an action or submit a form.

Variants:

• Primary
• Secondary
• Tertiary
• Destructive
• Ghost
• Link

Sizes:

• Small
• Medium
• Large

States:

• Default
• Hover
• Focus-Visible
• Pressed
• Loading
• Disabled

Icon Options:

• None
• Leading
• Trailing
• Icon Only

Width Options:

• Content Width
• Full Width

Recommended Props:

• variant
• size
• loading
• disabled
• iconStart
• iconEnd
• fullWidth
• type
• children

Behavior:

• Preserve width during loading.
• Prevent duplicate activation while loading.
• Use native button semantics.
• Do not use disabled styling for links.
• Provide accessible text for icon-only buttons.

Keyboard:

• Enter and Space activate native buttons.
• Focus must remain visible.

Content Rules:

• Use action-oriented labels.
• Avoid wrapping labels where possible.
• Do not rely on icons alone unless the control has an accessible name.

=== COMPONENT SPECIFICATION ===

Component: TextField

Purpose: Collect short-form user input.

Anatomy:

• Label
• Required indicator
• Input
• Prefix
• Suffix
• Leading icon
• Trailing action
• Helper text
• Error text
• Character count

States:

• Default
• Hover
• Focus
• Filled
• Disabled
• Read-Only
• Error
• Success
• Loading when asynchronous validation applies

Accessibility:

• Use a persistent label.
• Associate helper and error text programmatically.
• Preserve user input after validation errors.
• Use appropriate autocomplete attributes.
• Ensure trailing actions have accessible names.

=== COMPONENT SPECIFICATION ===

Component: Modal

Purpose: Present a focused task or decision without navigating away from the current context.

Variants:

• Informational
• Form
• Confirmation
• Destructive Confirmation
• Large Content

Required Behavior:

• Move focus into the modal.
• Trap focus while open.
• Close on Escape unless an irreversible process requires another rule.
• Restore focus to the trigger.
• Prevent background keyboard interaction.
• Provide a visible close control.
• Announce the modal title.

Responsive Behavior:

• Centered dialog on large screens.
• Full-width or near-full-width dialog on small screens.
• Use a bottom sheet only when interaction and content justify it.

=== COMPONENT SPECIFICATION ===

Component: DataTable

Purpose: Support exact-value scanning, comparison, sorting, filtering, selection, and row actions.

Required Configuration:

• Column definitions
• Alignment
• Minimum width
• Sorting
• Filtering
• Selection
• Row actions
• Bulk actions
• Pagination
• Loading
• Empty
• Error
• Permission state
• Responsive strategy

Responsive Options:

• Horizontal scroll
• Priority-column reduction
• Expandable rows
• Card transformation
• Detail-screen navigation

The implementation must explicitly select the appropriate strategy.

Accessibility:

• Use semantic table markup when the interaction model allows.
• Provide accessible column headers.
• Announce sorting changes.
• Preserve keyboard access.
• Avoid pointer-only row actions.

=== COMPONENT SPECIFICATION ===

Component: PricingCard

Purpose: Present plan information and support informed plan selection.

Anatomy:

• Plan name
• Audience fit
• Price
• Billing period
• Billing note
• Feature list
• Limits
• Recommended label
• CTA
• Terms note

Variants:

• Standard
• Recommended
• Enterprise
• Current Plan
• Disabled Or Unavailable

Integrity Rules:

• Display billing conditions clearly.
• Do not hide recurring charges.
• Do not use deceptive defaults.
• Explain material limits.
• Do not fabricate scarcity or discounts.

=== STATE MATRIX ===

Every interactive component should be reviewed for:

• Default
• Hover
• Focus-Visible
• Pressed
• Selected
• Disabled
• Loading
• Success
• Warning
• Error
• Empty
• Read-Only
• Permission Restricted
• Offline
• Partial Data

For each state, define:

• Trigger
• Visual change
• Content change
• Interaction
• Accessibility announcement
• Recovery
• Testing requirement

=== RESPONSIVE SYSTEM ===

Buttons:

• Preserve minimum touch size.
• Use full width only when hierarchy or mobile layout requires it.

Cards:

• Reflow from multi-column grids to stacked layouts.
• Do not force identical heights when content differs unless required.

Forms:

• Use full-width fields on narrow screens.
• Preserve label and error visibility.
• Prevent keyboard obstruction.

Tables:

• Use an explicitly approved responsive strategy.

Modals:

• Reduce margins and increase available content area on small screens.

Navigation:

• Convert persistent desktop navigation into an accessible mobile drawer.

Pricing:

• Stack plans while preserving complete price, limit, and billing information.

=== ACCESSIBILITY REQUIREMENTS ===

• Use semantic HTML.
• Maintain logical heading hierarchy.
• Provide accessible names.
• Support full keyboard interaction.
• Use visible focus indicators.
• Preserve logical focus order.
• Maintain sufficient color contrast.
• Do not rely on color alone.
• Use persistent field labels.
• Associate errors with controls.
• Provide error recovery.
• Manage modal and drawer focus.
• Provide tooltip access through keyboard and pointer interaction.
• Use semantic table structures.
• Support reduced motion.
• Support browser zoom and responsive reflow.
• Use sufficient touch-target sizes.
• Provide alternatives for drag-and-drop.
• Test screen-reader output for complex components.

=== STORYBOOK PLAN ===

Every component should include:

• Overview
• Anatomy
• Default Story
• Variants
• Sizes
• States
• Responsive Examples
• Accessibility Notes
• Content Guidelines
• Do And Do Not Examples
• Theme Examples
• API Documentation
• Design Tokens
• Testing Notes
• Migration Notes where relevant

Recommended Button Stories:

• Primary
• Secondary
• Destructive
• Sizes
• With Leading Icon
• With Trailing Icon
• Icon Only
• Loading
• Disabled
• Full Width
• Long Label
• Dark Theme

=== TESTING STRATEGY ===

Unit Tests:

• Prop behavior
• State transitions
• Content rendering
• Event handling

Interaction Tests:

• Keyboard behavior
• Pointer behavior
• Focus movement
• Overlay dismissal
• Form validation

Accessibility Tests:

• Accessible names
• Roles
• Labels
• Focus order
• Keyboard support
• Contrast review
• Screen-reader review

Visual Regression:

• Variants
• States
• Themes
• Breakpoints
• Long content
• Localization expansion

End-To-End Tests:

• Form submission
• Modal workflows
• Navigation
• Table actions
• Pricing selection
• Error recovery

=== NAMING CONVENTIONS ===

Component Names: Use clear PascalCase names based on purpose.

Props: Use consistent semantic names.

Preferred:

• variant
• size
• status
• loading
• disabled
• fullWidth
• iconStart
• iconEnd

Avoid:

• visual names tied to one color
• unclear abbreviations
• duplicate props with overlapping meaning
• boolean props that create conflicting combinations

Token Names: Use semantic, hierarchical naming.

Preferred: color.text.primary

Avoid: dark-gray-text

=== GOVERNANCE MODEL ===

Contribution Request:

1. Define the user and product problem.
2. Show repeated usage need.
3. Identify existing alternatives.
4. Propose component anatomy.
5. Define variants and states.
6. Define accessibility.
7. Define responsive behavior.
8. Add tests.
9. Add documentation.
10. Obtain design and engineering review.

New Component Criteria:

• Repeated use
• Shared structure
• Shared behavior
• Shared accessibility requirements
• Clear ownership
• Maintenance justification

A one-off product feature should not automatically become a shared component.

=== VERSIONING POLICY ===

Patch: Bug fixes that preserve the public API.

Minor: Backward-compatible features and variants.

Major: Breaking API, behavior, token, or styling changes.

Every release should include:

• Version
• Date
• Added
• Changed
• Fixed
• Deprecated
• Removed
• Migration requirements

=== DEPRECATION POLICY ===

1. Mark the component or API as deprecated.
2. Document the replacement.
3. Provide migration guidance.
4. Add development warnings where appropriate.
5. Define a removal version.
6. Track remaining usage.
7. Remove only according to the approved release policy.

=== MIGRATION STRATEGY ===

Phase 1: Audit existing components.

Phase 2: Map duplicates to approved components.

Phase 3: Implement foundations and tokens.

Phase 4: Migrate high-frequency components.

Phase 5: Migrate complex overlays, tables, and forms.

Phase 6: Remove deprecated components.

Phase 7: Verify themes, accessibility, responsive behavior, and visual consistency.

=== IMPLEMENTATION SEQUENCE ===

1. Confirm system users and technical stack.
2. Audit existing components.
3. Approve foundations and semantic tokens.
4. Approve naming conventions.
5. Implement layout primitives.
6. Implement buttons, links, and form controls.
7. Implement surfaces and feedback.
8. Implement navigation.
9. Implement overlays.
10. Implement tables and complex data components.
11. Implement product-specific composites.
12. Add Storybook documentation.
13. Add automated tests.
14. Complete accessibility review.
15. Complete responsive and visual regression review.
16. Publish migration documentation.
17. Establish governance and release ownership.

=== ACCEPTANCE CRITERIA ===

Button Keyboard Behavior:

Given a keyboard user focuses a standard button, when Enter or Space is pressed, then the button activates once, displays loading feedback when applicable, and prevents duplicate activation during processing.

Modal Focus Management:

Given a user opens a modal, when the modal appears, then focus moves to the first meaningful element, remains inside the modal, Escape closes it when permitted, and focus returns to the original trigger.

Text Field Error:

Given a field fails validation, when the error appears, then the entered value remains visible, the error is programmatically associated with the field, and the user can correct the value without restarting.

Responsive Pricing Cards:

Given the viewport is below the small-screen breakpoint, when pricing cards are displayed, then plans stack vertically and all material pricing, billing, feature, and limit information remains readable without horizontal overflow.

Dark Theme:

Given the dark theme is active, when any component is displayed, then semantic tokens provide sufficient contrast, focus remains visible, and state meaning is preserved without relying on color alone.

=== QA CHECKLIST ===

Foundation QA:

• Verify semantic tokens.
• Verify light and dark themes.
• Verify typography.
• Verify spacing.
• Verify radii.
• Verify shadows.
• Verify focus rings.
• Verify motion tokens.

Component QA:

• Verify anatomy.
• Verify required elements.
• Verify optional elements.
• Verify props.
• Verify variants.
• Verify sizes.
• Verify states.
• Verify long content.
• Verify missing content.
• Verify nested usage.

Interaction QA:

• Verify pointer behavior.
• Verify keyboard behavior.
• Verify focus management.
• Verify loading.
• Verify errors.
• Verify recovery.
• Verify disabled behavior.

Responsive QA:

• Verify all breakpoints.
• Verify touch targets.
• Verify form layouts.
• Verify navigation transformation.
• Verify table behavior.
• Verify modal behavior.
• Verify pricing-card behavior.

Accessibility QA:

• Verify semantics.
• Verify accessible names.
• Verify labels.
• Verify focus.
• Verify contrast.
• Verify screen-reader output.
• Verify reduced motion.
• Verify zoom and reflow.

Documentation QA:

• Verify Storybook stories.
• Verify API documentation.
• Verify design-token references.
• Verify usage guidance.
• Verify anti-patterns.
• Verify migration notes.

=== KNOWN LIMITATIONS ===

• Final source code requires implementation and technical review.
• Figma and frontend libraries require ongoing synchronization.
• Accessibility requires manual and automated testing.
• Visual regression requires an approved baseline.
• Browser support requires real browser testing.
• Complex product workflows may require dedicated domain components.
• The system does not guarantee complete adoption, reduced development time, or error-free releases.

=== FINAL SYSTEM NOTE ===

Treat the component system as a maintained product rather than a one-time design deliverable. Assign ownership, document decisions, test every public behavior, measure adoption, and evolve components through a controlled contribution and versioning process.