Primitive And App Surfaces

Why This Layer Exists

System completeness does not come from adding endless marketing variants. It comes from having reliable primitives, app shells, forms, data surfaces, and states that teams actually reuse.

This reference captures where primitive and app-surface logic belongs in Webspire: fewer novelty families, more dependable coverage.

Existing Families

These areas already exist in Webspire and should usually grow through variants, not through new family keys.

• Data and Tables → extend data-table, pagination, skeleton, report-header
• Forms and Inputs → extend forms, auth, search, tag-input, tabs
• Overlays and Feedback → extend drawer, popup, notification, tooltip, banner
• Navigation and App Shells → extend sidebar, navbar, mega-menu, breadcrumb
• Empty, Loading, Error States → extend empty-state, skeleton, spinner, error
• Commerce and Utility Controls → extend product-filter, wishlist, shopping-cart, order-summary

If a concept fits one of those buckets, do not create a new family by default.

Existing Anchors

These current Webspire patterns already define the shape of this composition layer:

• Tables and dense data → data-table/base, data-table/with-filter, pagination/with-info, report-header/with-tabs
• Forms and input flows → forms/base, forms/search, forms/multi-step, tag-input/with-suggestions
• Navigation and shells → sidebar/base, sidebar/collapsible, navbar/sidebar-push, breadcrumb/with-icon
• Auth and account entry → auth/base, auth/social, auth/forgot-password
• Feedback and overlays → notification/stacked, drawer/with-tabs, popup/base, tooltip/info
• States and fallbacks → skeleton/table, spinner/dots, empty-state/with-action, error/split

First-Class Families

Only a small set deserves stronger family-level treatment because it represents recurring product structure, not just styling.

• Settings → account preferences, notification controls, workspace configuration, billing controls
• Profiles → account overviews, member cards, identity panels, role summaries
• Notification → inbox-like alert centers, stacked updates, status-driven feedback
• Auth → sign-in, register, social auth, recovery, role-aware entry
• Sidebar → persistent app shells, settings rails, contextual navigation

These already exist in the taxonomy and belong as first-class product surfaces.

Variant Space

These variants fit naturally inside the existing family system:

• data-table/toolbar-heavy
• data-table/compact
• data-table/selectable
• forms/two-column
• forms/inline-validation
• forms/filter-bar
• sidebar/app-shell
• sidebar/settings-nav
• auth/compact-card
• auth/split-brand
• notification/inbox-panel
• skeleton/content-page
• pagination/compact
• breadcrumb/with-icon
• drawer/slide-over-detail

These belong as variants under existing families, not as new top-level groups.

Ideas Better As Snippets

Some useful UI polish belongs in the snippet layer because it is cross-family behavior.

• Modal Scale Fade → overlay entry/exit rhythm
• Dropdown Origin Shift → menu motion with clear anchor direction
• Sidebar Slide Over → small-screen navigation behavior
• Input Focus Ring System → consistent focus treatment across controls
• Table Row Highlight → active and hover states for dense data
• Skeleton Shimmer Soft → gentler loading motion
• Tab Indicator Slide → directional state changes in tabbed interfaces

These should compose with many families instead of locking behavior into one pattern.

Existing snippet anchors for this layer:

• interactions/focus-ring
• interactions/modal-scale-fade
• interactions/dropdown-origin-shift
• interactions/sidebar-slide-over
• interactions/table-row-highlight
• animations/skeleton-shimmer-soft
• interactions/tab-indicator-slide

RTL And International Readiness

RTL should not become its own family. It should become a capability expectation for the families that most often break when direction flips.

Prioritize RTL-safe variants and review for:

• navbar
• sidebar
• breadcrumb
• pagination
• forms
• tabs
• data-table
• timeline

The goal is logical spacing, reversible layout assumptions, and fewer left/right hard-codes.

What Not To Add

Avoid creating new families for concepts that are really just one of these:

• a table with different density
• a form with different grouping
• a sidebar with different chrome
• a dropdown with different motion
• an auth page with different illustration treatment

Those belong in variants, snippets, or semantics, not new taxonomy branches.

Composition Boundary

If a concept is mostly density, grouping, chrome, or interaction treatment, it belongs in variants or snippets.

If it represents a recurring product surface with its own structure, state model, and semantics, it belongs as a first-class family.

This is why data-table, forms, sidebar, auth, notification, and settings belong in composition, while things like focus styling, shimmer, motion direction, and hover treatment do not.

Design Principle

This layer should make Webspire feel more complete for real products, not noisier. Good system expansion reduces decision load, increases reusability, and keeps the taxonomy stable enough that AI and MCP can reason over it.