Introduce custom-tags based natural design system

[shah]

We are standardizing on a custom-tags based HTML approach (example: <natural-layout>, <natural-brand-bar>, etc.) and need to flesh out a complete semantic design system built on modern HTML and modern CSS. The goal is a cohesive, accessible, composable set of “natural-*” tags that can be used in plain HTML (no framework requirement) while remaining easy to adopt in React/Vue/Svelte later.

This ticket covers defining the vocabulary (tag catalog), the semantics (slots/regions), the CSS architecture (tokens, layers, theming), and the reference implementation (natural.css + an index.html reference page).

Goals

• Define a consistent custom-tag naming and composition model for layout, navigation, content, forms, and utilities.
• Implement a modern CSS foundation (tokens, cascade layers, container queries where useful, modern selectors).
• Ensure accessibility defaults (ARIA patterns, focus management, keyboard nav) for interactive primitives.
• Provide a reference “kitchen sink” page that documents and demonstrates every component/tag.
• Keep the design system framework-agnostic: works with plain HTML, progressively enhanced with minimal JS only when needed.

Non-goals

• No dependency on Web Components APIs required initially (can be added later if beneficial).
• No JS-heavy component framework implementation in this ticket (only minimal progressive enhancement where necessary, like menus).

Deliverables

1. Spec: Natural Design System (NDS)

• Tag catalog and conventions

  • Naming: natural-* tags, internal child tags (natural--left/right/slot), attribute conventions (data-active, data-variant, data-size, data-tone, aria-).
  • Composition: how tags nest; required/optional children; allowed content types.
  • States: hover/focus/active/disabled/loading/selected/error.

• Layout + structure tags

  • natural-layout, natural-page, natural-header, natural-main, natural-footer
  • natural-container, natural-grid, natural-stack, natural-split, natural-sidebar-layout
  • natural-divider, natural-spacer

• Navigation + shell tags

  • natural-brand-bar and related regions (natural-brand-left, natural-app-links, natural-personalization)
  • natural-breadcrumbs, natural-tabs, natural-nav, natural-subnav
  • natural-user-dropdown, natural-user-menu

• Content + display tags

  • natural-card, natural-card-header/body/footer
  • natural-panel, natural-callout, natural-badge, natural-tag
  • natural-table (+ column helpers if needed)
  • natural-kpi, natural-stat, natural-progress

• Form + input tags

  • natural-form, natural-field, natural-label, natural-help, natural-error
  • natural-input, natural-textarea, natural-select, natural-checkbox, natural-radio, natural-switch
  • natural-button, natural-button-group

• Feedback + overlays tags

  • natural-toast, natural-alert, natural-modal, natural-drawer
  • natural-tooltip, natural-popover
  • natural-notification-badge

• Media + identity tags

  • natural-avatar, natural-icon, natural-logo, natural-figure

2. CSS architecture

• natural.css with:

  • Design tokens via CSS variables (color, typography, spacing, radius, shadow, z-index, motion).
  • Cascade layers (@layer reset, base, tokens, components, utilities).
  • Dark mode support via prefers-color-scheme plus a manual override attribute (data-theme="dark|light").
  • Responsive patterns using clamp(), container queries where appropriate, logical properties, and modern selectors (:where, :is).
  • Accessible focus styles (focus-visible), reduced motion (prefers-reduced-motion).
  • Print styles (basic).

3. Minimal progressive enhancement JS (only where needed)

• Dropdown/menu behavior for natural-user-dropdown + natural-user-menu

  • Keyboard navigation, ESC to close, click outside to close, aria-expanded toggling.

• Optional: tabs and modal behavior if included in the reference page.

4. Reference documentation page

• index.html “kitchen sink” page showing:

  • Brand bar + app links + personalization and user dropdown
  • Typography scale, spacing examples
  • Buttons, badges, cards, forms, tables, alerts/toasts, etc.
  • Multiple themes (light/dark) and variants.

Acceptance criteria

• A developer can build a full app shell using only the custom tags and natural.css.

• Every interactive primitive demonstrated passes basic keyboard navigation:

  • Tab/Shift-Tab works, focus visible, menu opens/closes correctly, ESC closes.

• All components have sensible accessible defaults (ARIA only where required; semantic HTML where possible inside custom tags).

• natural.css is organized with cascade layers and tokens; no major specificity wars.

• The reference page renders cleanly in current evergreen browsers (Chrome, Edge, Firefox, Safari).

• Tag catalog and composition rules are documented in a README or in-page documentation.

Implementation notes / suggestions

• Prefer styling by element selector (natural-button { ... }) and low-specificity wrappers (:where(natural-card) { ... }).

• Use attributes for variants instead of new tags when possible:

  • data-variant="primary|secondary|ghost"
  • data-size="sm|md|lg"
  • data-tone="info|success|warning|danger"

• Consider using inert + dialog element for modals later, but keep first pass minimal.

Tasks

• Create /docs/design-system/README.md with tag catalog + conventions
• Implement /natural.css with tokens + layers + base component styles
• Build /index.html reference page expanding beyond brand bar
• Add /natural.js for dropdown behavior (and any other minimal behaviors)
• Add basic visual regression screenshots (optional) or at least a manual QA checklist