Web App UI Component System Builder

=== 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.