@cruglobal/cornerstone-components 0.1.0

package/dist/unbundled/skills/cornerstone/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: cornerstone
+description: Cornerstone is a UI component library built with web components. Use when building buttons, inputs, selects, checkboxes, dialogs, modals, drawers, tabs, dropdowns, tooltips, carousels, forms, or using CSS utilities like cs-stack, cs-cluster, cs-grid, cs-prose. Supports React, Vue, Angular, Svelte, and vanilla JS.
+license: MIT
+metadata:
+  author: Cru Global
+  version: "0.1.0"
+  homepage: https://cruglobal.github.io/cornerstone-design-system
+  repository: https://github.com/CruGlobal/cornerstone-design-system
+compatibility: Works in modern browsers. Requires no build tools when using CDN. Works with bundlers like Webpack and Vite when installed via npm.
+allowed-tools: Read
+---
+
+# Cornerstone
+
+Cornerstone Components is the open source custom-element library of the Cornerstone design system. It provides 70 accessible, customizable web components that work with any framework.
+
+> **Designing with Cornerstone?** For full-page layout (`<cs-page>`), theming, brand color, and visual composition guidance, install the companion **`cornerstone-design`** skill. This skill is the component reference; that one teaches how to put components together into a polished UI. See [Agent Skills](https://cruglobal.github.io/cornerstone-design-system/ai/agent-skills) for both.
+
+## Quick Start
+
+### npm Installation
+
+```bash
+npm install @cruglobal/cornerstone-components
+```
+
+Import styles and components:
+
+```js
+import '@cruglobal/cornerstone-components/styles/cornerstone.css';
+import '@cruglobal/cornerstone-components/components/button/button.js';
+```
+
+### Loading in the browser without a bundler
+
+The package ships two builds. The unbundled build (imported above) keeps its dependencies as bare
+specifiers, so it needs a bundler. The bundled build inlines them, so a browser can load it directly:
+
+```html
+<link rel="stylesheet" href="/node_modules/@cruglobal/cornerstone-components/dist/bundled/styles/cornerstone.css" />
+<script type="module" src="/node_modules/@cruglobal/cornerstone-components/dist/bundled/cornerstone.loader.js"></script>
+```
+
+For detailed installation options, see [Installation Guide](references/installation.md).
+
+## Core Concepts
+
+Cornerstone components are custom HTML elements. They work like native elements but with enhanced functionality.
+
+- **Attributes & Properties**: Configure components via HTML attributes or JavaScript properties
+- **Events**: Listen to custom events prefixed with `cs-` (e.g., `cs-change`, `cs-input`)
+- **Methods**: Call methods programmatically (e.g., `element.focus()`)
+- **Slots**: Insert content into named slots (e.g., `<cs-icon slot="start">`)
+- **CSS Parts**: Style internal elements using `::part()` selectors
+- **CSS Custom Properties**: Customize appearance with CSS variables
+
+**Important**: Always use closing tags. Custom elements cannot self-close.
+
+```html
+<!-- Correct -->
+<cs-input></cs-input>
+
+<!-- Incorrect - will not work -->
+<cs-input />
+```
+
+For complete usage details, see [Usage Guide](references/usage.md).
+
+## Components
+
+> **Not sure which one to pick?** See [Choosing the right component](references/choosing-components.md)
+> — a decision tree organized by user intent. Most agent mistakes here are picking the wrong component
+> (e.g. `<cs-dropdown>` instead of `<cs-select>`), not API misuse.
+
+#### Actions
+
+- [`<cs-button>`](references/components/button.md) - Buttons represent actions the user can take, such as submitting a form, opening a dialog, or navigating to another page. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/button))
+- [`<cs-button-group>`](references/components/button-group.md) - Button groups combine related buttons into a single visual unit. Use them for toolbars, segmented controls, or any set of actions that belong together. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/button-group))
+- [`<cs-copy-button>`](references/components/copy-button.md) - Copy buttons copy text to the clipboard when the user activates them. They provide built-in success and error feedback so users know the copy worked. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/copy-button))
+- [`<cs-dropdown>`](references/components/dropdown.md) - Dropdowns display a list of options triggered by a button or other element. They support keyboard navigation, submenus, and checkable items for building menus and context actions. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/dropdown))
+- [`<cs-dropdown-item>`](references/components/dropdown-item.md) - Dropdown items represent selectable entries within a dropdown menu, including standard actions, checkable items, and submenu triggers. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/dropdown-item))
+
+#### Feedback
+
+- [`<cs-badge>`](references/components/badge.md) - Badges draw attention to adjacent content by displaying a status, count, or label. Use them to highlight notifications, categorize items, or flag new activity. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/badge))
+- [`<cs-callout>`](references/components/callout.md) - Callouts display important messages inline with surrounding content. Use them to highlight tips, warnings, errors, or other information users should not miss. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/callout))
+- [`<cs-progress-bar>`](references/components/progress-bar.md) - Progress bars show how far along an ongoing operation is as a horizontal fill. Use them for file uploads, multi-step flows, or any task with measurable progress. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/progress-bar))
+- [`<cs-progress-ring>`](references/components/progress-ring.md) - Progress rings show how far along a determinate operation is using a circular indicator. Use them as a compact alternative to progress bars when horizontal space is limited. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/progress-ring))
+- [`<cs-skeleton>`](references/components/skeleton.md) - Skeletons show placeholder shapes where content will appear once it finishes loading, reducing perceived wait time and preventing layout shift. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/skeleton))
+- [`<cs-spinner>`](references/components/spinner.md) - Spinners indicate that an operation is in progress when the duration is unknown. Use them for loading states where a determinate progress bar isn't practical. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/spinner))
+- [`<cs-tag>`](references/components/tag.md) - Tags label, categorize, or represent selections with a compact visual marker. Use them for status indicators, filters, or removable chips. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/tag))
+- [`<cs-toast>`](references/components/toast.md) - Toasts display brief, non-blocking notifications that appear temporarily above the page content. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/toast))
+- [`<cs-toast-item>`](references/components/toast-item.md) - Toast items are individual notifications displayed within a toast container. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/toast-item))
+- [`<cs-tooltip>`](references/components/tooltip.md) - Tooltips display brief contextual information when the user hovers, focuses, or taps a target element. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/tooltip))
+
+#### Forms
+
+- [`<cs-checkbox>`](references/components/checkbox.md) - Checkboxes let users toggle an option on or off, or select multiple items from a list. They also support an indeterminate state for partial selections in groups. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/checkbox))
+- [`<cs-checkbox-group>`](references/components/checkbox-group.md) - Checkbox groups wrap a set of related checkboxes or switches so they share a label, hint, and grouping semantics. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/checkbox-group))
+- [`<cs-color-picker>`](references/components/color-picker.md) - Color pickers let users choose a color from a visual palette or by entering a value. They support HEX, RGB, HSL, and HSV formats with optional alpha channel and swatch presets. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/color-picker))
+- [`<cs-input>`](references/components/input.md) - Inputs collect single-line data from the user, such as text, numbers, email addresses, and passwords. They support labels, hints, validation, and prefix or suffix slots. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/input))
+- [`<cs-known-date>`](references/components/known-date.md) - Known dates let users enter dates they already know - birthdays, expirations, document dates - through three separate day, month, and year fields shown in the locale's natural order. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/known-date))
+- [`<cs-number-input>`](references/components/number-input.md) - Number inputs let users enter and edit numeric values, with optional stepper buttons for incrementing and decrementing. Use them for quantities, measurements, and other numeric form fields. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/number-input))
+- [`<cs-option>`](references/components/option.md) - Options represent the individual choices inside a select or similar form control. Each option holds a value and the label shown to the user. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/option))
+- [`<cs-otp-input>`](references/components/otp-input.md) - OTP inputs collect one-time passcodes, PINs, and other fixed-length codes, one character per segment. Use them for SMS verification, two-factor authentication, and invite codes. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/otp-input))
+- [`<cs-radio>`](references/components/radio.md) - Radios represent a single option within a mutually exclusive set. Use them inside a radio group when users must pick exactly one choice from a small list. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/radio))
+- [`<cs-radio-group>`](references/components/radio-group.md) - Radio groups wrap a set of radios so they function as a single form control with one shared value. They handle keyboard navigation, labeling, and validation for the group as a whole. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/radio-group))
+- [`<cs-rating>`](references/components/rating.md) - Ratings display a numeric score as a row of selectable symbols, typically stars. Use them to capture quick feedback or show an average rating for a product or piece of content. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/rating))
+- [`<cs-select>`](references/components/select.md) - Selects let users choose one or more values from a dropdown list of predefined options. Use them in forms when a fixed set of choices needs to fit in limited space. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/select))
+- [`<cs-slider>`](references/components/slider.md) - Sliders let users choose a numeric value within a defined range by dragging a thumb along a track. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/slider))
+- [`<cs-switch>`](references/components/switch.md) - Switches toggle a single setting on or off and apply the change immediately, without requiring a form submission. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/switch))
+- [`<cs-textarea>`](references/components/textarea.md) - Textareas collect multi-line text input from the user, with optional resizing and character counting. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/textarea))
+- [`<cs-time-input>`](references/components/time-input.md) - Time pickers let users enter a time through a segmented field or select one visually from a popup column picker. They support 12- and 24-hour formats, optional seconds, and locale-aware segment order. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/time-input))
+
+#### Helpers
+
+- [`<cs-animation>`](references/components/animation.md) - Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the Web Animations API. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/animation))
+- [`<cs-format-bytes>`](references/components/format-bytes.md) - Formats a number of bytes as a human-readable string with the appropriate unit, such as kB, MB, or GB. Supports both byte and bit units with configurable locale. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/format-bytes))
+- [`<cs-format-date>`](references/components/format-date.md) - Formats a date or time for display using the specified locale and options. Powered by the Intl.DateTimeFormat API for consistent, localized output. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/format-date))
+- [`<cs-format-number>`](references/components/format-number.md) - Formats a number for display using the specified locale and options, including currency, percent, and unit styles. Powered by the Intl.NumberFormat API. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/format-number))
+- [`<cs-include>`](references/components/include.md) - Fetches an external HTML file and embeds its contents inline on the page. Useful for reusing shared markup like headers, footers, and partials across multiple pages. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/include))
+- [`<cs-intersection-observer>`](references/components/intersection-observer.md) - Tracks immediate child elements and fires events as they move in and out of view. Useful for lazy loading, scroll-triggered animations, and viewport-aware interactions. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/intersection-observer))
+- [`<cs-mutation-observer>`](references/components/mutation-observer.md) - Mutation observers watch for changes to an element's DOM tree and emit an event when they occur. Provides a thin, declarative interface to the browser's MutationObserver API. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/mutation-observer))
+- [`<cs-popover>`](references/components/popover.md) - Popovers display contextual content and interactive elements in a floating panel anchored to a trigger. Use them for rich tooltips, menus, or any content that appears on demand without navigating away. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/popover))
+- [`<cs-popup>`](references/components/popup.md) - Popups declaratively anchor one element to another and keep them positioned together as the page scrolls or resizes. Primarily a low-level building block for popovers, dropdowns, and tooltips. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/popup))
+- [`<cs-random-content>`](references/components/random-content.md) - Selects one or more child elements at random and displays them, hiding the rest. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/random-content))
+- [`<cs-relative-time>`](references/components/relative-time.md) - Relative times display a date as a localized phrase relative to now, such as "3 hours ago" or "in 2 days". The phrase updates automatically as time passes and respects the user's locale. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/relative-time))
+- [`<cs-resize-observer>`](references/components/resize-observer.md) - Resize observers watch their slotted elements for size changes and emit an event when they occur. Provides a thin, declarative interface to the browser's ResizeObserver API. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/resize-observer))
+
+#### Layout
+
+- [`<cs-accordion>`](references/components/accordion.md) - Accordions are a vertically stacked set of interactive headings that each contain a title, representing a section of content. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/accordion))
+- [`<cs-accordion-item>`](references/components/accordion-item.md) - Accordion items are used inside `<cs-accordion>` to create expandable sections with accessible headers. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/accordion-item))
+- [`<cs-card>`](references/components/card.md) - Cards group related content and actions inside a bordered container. Use them to present products, articles, user profiles, or any self-contained unit of information. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/card))
+- [`<cs-details>`](references/components/details.md) - Details display a brief summary and expand to reveal additional content. Use them to progressively disclose information, group related FAQs, or hide advanced options. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/details))
+- [`<cs-dialog>`](references/components/dialog.md) - Dialogs appear above the page and require the user's immediate attention. Use them for confirmations, forms, or focused tasks that interrupt the main flow. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/dialog))
+- [`<cs-divider>`](references/components/divider.md) - Dividers visually separate or group adjacent elements with a horizontal or vertical line. Use them to establish rhythm and hierarchy within menus, toolbars, and layouts. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/divider))
+- [`<cs-drawer>`](references/components/drawer.md) - Drawers slide in from the edge of a container to expose additional options and information without navigating away. Useful for navigation menus, filters, and secondary content. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/drawer))
+- [`<cs-page>`](references/components/page.md) - Pages scaffold an entire application layout with header, navigation, sidebar, main content, aside, and footer regions. Use them to structure full pages with minimal markup and responsive behavior built in. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/page))
+- [`<cs-scroller>`](references/components/scroller.md) - Scrollers wrap overflowing content in an accessible container with visual cues that help users recognize and navigate scrollable regions. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/scroller))
+- [`<cs-split-panel>`](references/components/split-panel.md) - Split panels display two adjacent panels separated by a draggable divider, letting users resize each side to suit their workflow. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/split-panel))
+
+#### Media
+
+- [`<cs-animated-image>`](references/components/animated-image.md) - Animated images display GIFs and WEBPs with controls to play and pause them on demand. Use them when you want motion but need to give users control over when it plays. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/animated-image))
+- [`<cs-avatar>`](references/components/avatar.md) - Avatars represent a person or object with an image, initials, or icon. Use them in lists, comments, and profiles to give users visual context at a glance. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/avatar))
+- [`<cs-carousel>`](references/components/carousel.md) - Carousels display a series of content slides along a horizontal or vertical axis, one or more at a time. Users can navigate between slides with controls, pagination, or autoplay. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/carousel))
+- [`<cs-carousel-item>`](references/components/carousel-item.md) - Carousel items represent individual slides within a carousel. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/carousel-item))
+- [`<cs-comparison>`](references/components/comparison.md) - Comparisons show the visual differences between two pieces of similar content using a draggable divider. Use them for before/after images, design revisions, or side-by-side previews. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/comparison))
+- [`<cs-icon>`](references/components/icon.md) - Icons are scalable vector symbols that represent actions, content, or status throughout your application. They support Material Symbols and custom icon libraries with animation presets. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/icon))
+- [`<cs-markdown>`](references/components/markdown.md) - Markdown elements render markdown content as HTML directly in the browser, making it easy to display user-generated content or documentation without a server-side build step. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/markdown))
+- [`<cs-qr-code>`](references/components/qr-code.md) - QR codes encode a URL or other short text into a scannable image, rendered client-side using the Canvas API. Use them to share links, contact info, or Wi-Fi credentials that visitors can scan with a phone. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/qr-code))
+- [`<cs-zoomable-frame>`](references/components/zoomable-frame.md) - Zoomable frames embed iframe content with built-in controls for zooming, panning, and managing interaction. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/zoomable-frame))
+
+#### Navigation
+
+- [`<cs-breadcrumb>`](references/components/breadcrumb.md) - Breadcrumbs display a trail of links that show users where they are in a site's hierarchy. They help users understand the current location and navigate back to parent pages. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/breadcrumb))
+- [`<cs-breadcrumb-item>`](references/components/breadcrumb-item.md) - Breadcrumb items represent individual links inside a breadcrumb, typically one per level of the site hierarchy. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/breadcrumb-item))
+- [`<cs-pagination>`](references/components/pagination.md) - Pagination splits long lists of content into pages, letting users navigate between them. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/pagination))
+- [`<cs-tab>`](references/components/tab.md) - Tabs label and activate an individual panel inside a tab group. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/tab))
+- [`<cs-tab-group>`](references/components/tab-group.md) - Tab groups organize related content into a single container that displays one panel at a time, with tabs for switching between them. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/tab-group))
+- [`<cs-tab-panel>`](references/components/tab-panel.md) - Tab panels hold the content shown for a single tab inside a tab group. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/tab-panel))
+- [`<cs-tree>`](references/components/tree.md) - Trees allow you to display a hierarchical list of selectable tree items. Items with children can be expanded and collapsed as desired by the user. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/tree))
+- [`<cs-tree-item>`](references/components/tree-item.md) - Tree items represent a single hierarchical node inside a tree, and can contain nested items that expand and collapse. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/tree-item))
+
+## Building Full Pages with `<cs-page>`
+
+`<cs-page>` scaffolds an entire page layout (banner, header, navigation, main content, aside,
+footer) with responsive behavior built in. Most layout bugs come from a few specific mistakes —
+read this before generating a page.
+
+### Main content goes in the DEFAULT slot — there is no `main` slot
+
+Put your primary content directly inside `<cs-page>` with **no `slot` attribute**. There is
+**no slot named `main`**. Writing `<main slot="main">` sends the element to a slot that does not
+exist, so it is dropped and **the entire page renders blank**. This failure is silent — no error,
+no warning.
+
+```html
+<!-- Correct: <main> is unslotted, so it lands in the default slot -->
+<cs-page>
+  <main>...your sections...</main>
+</cs-page>
+
+<!-- WRONG: there is no "main" slot — the page body disappears -->
+<cs-page>
+  <main slot="main">...</main>
+</cs-page>
+```
+
+### Valid slots (use these exact names)
+
+`banner`, `header`, `subheader`, `navigation-header`, `navigation`,
+`navigation-footer`, `menu`, `main-header`, `main-footer`, `aside`, `footer`,
+`skip-to-content`, `navigation-toggle`. **Anything else** (e.g. `slot="main"`, `slot="nav"`,
+`slot="content"`) is silently ignored. There is no `nav` slot — the navigation slot is
+`navigation`. (`menu` is an advanced escape hatch that *replaces* the entire left navigation
+region; don't use it for ordinary nav links — and for a landing page, skip the left region
+entirely, see below.)
+
+### Navigation: a landing page needs nav in the `header` ONLY — do NOT use the `navigation` slot
+
+This is the #1 `<cs-page>` bug, and it comes from a wrong mental model. **The `navigation` slot
+is a persistent left sidebar, not a top nav bar.** On desktop it renders as a vertical menu column
+down the **left side** of the page (the `menu` region), and on mobile it collapses into a slide-out
+drawer. It is for **app layouts** (docs sites, dashboards) — NOT for a marketing landing page.
+
+A landing page's nav belongs in the **`header`** slot (the sticky top bar). If you put your links
+in the `header` **and also** in a `<… slot="navigation">`, you get **both at once on desktop**: the
+top bar AND a duplicate vertical list down the left side. That is the duplicated nav you must avoid.
+
+**Rule for landing pages: put nav links inline in the `header` slot and do not add a `navigation`
+(or `menu`) slot at all.** You do not need it, and adding it is what creates the duplicate.
+
+Mobile toggle for a header-only nav: `<cs-page>` auto-hides any element with `[data-toggle-nav]`
+on desktop and shows it on mobile (and `.cs-mobile-only` / `.cs-desktop-only` are honored too), so
+put a toggle button in the header with `data-toggle-nav` and wire it to show/hide your own header
+links — no media query needed. (Note: the component's built-in hamburger only appears when a
+`navigation` slot has content and you haven't supplied your own toggle; with header-only nav it
+stays hidden, which is what you want.)
+
+**Only** use the `navigation` slot if you genuinely want a left sidebar layout. In that case put
+the links there **only**, leave the `header` free of nav links, and you get the responsive drawer
+for free. Never list the same links in both `header` and `navigation`.
+
+### Zero the page reset AND mind the slot padding
+
+1. Zero `<html>`/`<body>` padding & margin or you get gaps:
+   ```css
+   html, body { min-height: 100%; padding: 0; margin: 0; }
+   ```
+2. **Always zero the padding on the default (main) slot.** Every slot region already has its own
+   `padding` and `gap`, including the default (main) slot. That built-in main padding is the most
+   common layout bug: it insets your full-bleed bands and, combined with any padding you add to
+   `<main>` or section wrappers, **stacks** and overflows on mobile. So always start by zeroing it
+   and control spacing yourself per section:
+   ```css
+   /* Always do this — then add your own padding inside each section. */
+   cs-page::part(main-content) { padding: 0; }
+   ```
+   With the main slot zeroed, give each section the horizontal padding it needs (and let full-bleed
+   sections run edge to edge). Don't add padding to `<main>` itself — pad the sections inside it.
+
+### Minimal complete example
+
+This is a landing page, so nav lives in the `header` only — there is **no `navigation` slot**.
+
+```html
+<html class="cs-light">
+  <head>
+    <style>
+      html, body { min-height: 100%; padding: 0; margin: 0; }
+
+      /* Zero the built-in padding on the main slot AND on the slotted <main>,
+         then pad each section yourself. (::part alone doesn't remove the
+         padding cs-page puts on a slotted <main>/<section>.) */
+      cs-page::part(main-content) { padding: 0; }
+      cs-page > main { padding: 0; }
+
+      /* Header nav: visible on desktop, hidden on mobile until toggled open. */
+      .header-links { display: flex; gap: var(--cs-space-l); }
+      cs-page[view='mobile'] .header-links { display: none; }
+      cs-page[view='mobile'][nav-open] .header-links {
+        display: flex; flex-direction: column;
+        position: absolute; inset-block-start: 100%; inset-inline: 0;
+        padding: var(--cs-space-m); background: var(--cs-color-surface-default);
+      }
+    </style>
+  </head>
+  <body>
+    <cs-page mobile-breakpoint="768">
+      <div slot="banner">Free shipping this week!</div>
+
+      <header slot="header" class="cs-split" style="position: relative;">
+        <a href="#">Brand</a>
+        <nav class="header-links">
+          <a href="#features">Features</a>
+          <a href="#pricing">Pricing</a>
+        </nav>
+        <!-- Auto-hidden on desktop, shown on mobile. Toggles [nav-open] on the page. -->
+        <cs-button data-toggle-nav appearance="plain" class="cs-mobile-only">
+          <cs-icon name="menu" label="Menu"></cs-icon>
+        </cs-button>
+      </header>
+
+      <!-- Main content: unslotted (default slot). NEVER slot="main". -->
+      <main>
+        <section>...</section>
+      </main>
+
+      <footer slot="footer">© 2026 Brand</footer>
+    </cs-page>
+  </body>
+</html>
+```
+
+(`data-toggle-nav` toggles the page's `nav-open` attribute, which the CSS above uses to reveal the
+header links on mobile. No JavaScript and no `navigation` slot required.)
+
+See the full reference at [`<cs-page>`](references/components/page.md) and
+https://cruglobal.github.io/cornerstone-design-system/components/page.
+
+## Themes
+
+Cornerstone includes pre-built themes. Apply a theme by adding its class to the `<html>` element.
+
+- **Default** - The foundational theme
+- **Awesome** - Bright, vibrant color palette
+- **Shoelace** - Classic Shoelace styling
+
+See [Themes Reference](references/themes.md) for usage details.
+
+## Color Palettes
+
+Each palette provides 10 color hues with 11 tints each.
+
+- Default, Base, Bright, Shoelace
+
+See [Themes Reference](references/themes.md) for palette usage.
+
+## Utilities
+
+Cornerstone provides CSS utilities for common styling tasks:
+
+- **Layout**: `cs-stack`, `cs-cluster`, `cs-grid`, `cs-split`, `cs-flank`, `cs-frame`
+- **Spacing**: `cs-gap-*` utilities
+- **Text**: Typography utilities
+- **Color**: Color variant utilities
+- **Rounding**: `cs-border-radius-*` utilities
+- **Prose**: `cs-prose` for long-form typographic rhythm (articles, docs, marketing copy)
+- **Accessibility**: `cs-visually-hidden` utilities
+- **FOUCE Prevention**: `cs-cloak` utility
+- **Native Styles**: Enhanced styling for native HTML elements
+
+See [Layout Utilities](references/utilities/layout.md), [Prose](references/utilities/prose.md), [Rounding](references/utilities/rounding.md), [Visually Hidden](references/utilities/visually-hidden.md), [FOUCE](references/utilities/fouce.md), and [Native Styles](references/utilities/native.md).
+
+## Design Tokens
+
+Cornerstone uses CSS custom properties (design tokens) for consistent theming:
+
+- **Borders**: `--cs-border-*` for width, radius, style
+- **Color**: `--cs-color-*` for surfaces, text, semantic colors
+- **Space**: `--cs-space-*` for consistent spacing
+- **Typography**: `--cs-font-*` for font families, sizes, weights
+- **Shadows**: `--cs-shadow-*` for elevation
+- **Focus**: `--cs-focus-*` for focus ring styles
+- **Transitions**: `--cs-transition-*` for animation timing
+
+See [Design Tokens](references/tokens/) for full reference.
+
+## Form Controls
+
+Cornerstone form controls are form-associated custom elements supporting native form validation and the Constraint Validation API.
+
+- Use `required`, `pattern`, `minlength`, `maxlength` attributes
+- Use `setCustomValidity()` for custom error messages
+- Style validation states with `:state(valid)`, `:state(invalid)`, etc.
+
+See [Form Controls Reference](references/form-controls.md) for details.
+
+## Icons
+
+Material Symbols is the default icon library. Use `<cs-icon>` with Material Symbols icon names, which are
+snake_case:
+
+```html
+<cs-icon name="home"></cs-icon>
+<cs-icon name="settings"></cs-icon>
+<cs-icon name="check"></cs-icon>
+```
+
+Three attributes select the cut. `family` picks the style — `sharp` (default), `outlined`, or `rounded`.
+`variant="fill"` draws the solid shape instead of the outline. `weight` takes 100–700 and defaults to 400.
+
+```html
+<cs-icon name="star" variant="fill"></cs-icon>
+<cs-icon name="star" weight="700" variant="fill"></cs-icon>
+```
+
+Material Symbols has no brand logos, so those come from the `brands` library:
+
+```html
+<cs-icon library="brands" name="github" label="GitHub"></cs-icon>
+```
+
+## Framework Integration
+
+Cornerstone works with any framework:
+
+- **React 19+**: Native custom element support with TypeScript types
+- **React 18 and below**: Use provided React wrappers
+- **Vue**: Works out of the box
+- **Angular**: Works out of the box
+- **Svelte**: Works out of the box
+
+See framework-specific guides in [references/frameworks/](references/frameworks/).
+
+## Support
+
+- **GitHub Issues**: https://github.com/CruGlobal/cornerstone-design-system/issues
+
+See [Support Reference](references/support.md) for more details.
+
+## Reference Documentation
+
+- [Choosing the Right Component](references/choosing-components.md) — decision tree by user intent (start here if you're unsure which component fits)
+- [Installation Guide](references/installation.md)
+- [Usage Guide](references/usage.md)
+- [Form Controls](references/form-controls.md)
+- [Customizing](references/customizing.md)
+- [Localization](references/localization.md)
+- [Themes & Palettes](references/themes.md)
+- [Layout Utilities](references/utilities/layout.md)
+- [Native Styles](references/utilities/native.md)
+- [Design Tokens](references/tokens/) - Borders, Color, Space, Typography, Shadows, Focus, Transitions
+- [Framework Guides](references/frameworks/)

package/dist/unbundled/skills/cornerstone/references/choosing-components.md

@@ -0,0 +1,201 @@
+# Choosing the right component
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/components
+
+When you reach for a Cornerstone component, start from **user intent** — what you need the user to do
+or see — not from the component name. Most agent mistakes here aren't API misuse; they're picking the
+wrong component for the job (using `<cs-dropdown>` when the user really needs `<cs-select>`, or hand-rolling
+a callout out of `<div>`s when `<cs-callout>` exists). Walk the tree below to the leaf that matches your
+intent, then check that component's individual reference for its API.
+
+The major decisions:
+
+- **Pick one from a set** — radio group, select, switch, slider, rating, color picker
+- **Pick many** — multiple checkboxes, multi-select
+- **Trigger an action** — button, copy button, dropdown menu, button group, tabs
+- **Show feedback or status** — callout, toast, badge, spinner, progress, skeleton, tooltip, popover
+- **Capture input** — input, number input, textarea
+- **Show data** — format helpers, relative time, QR code, comparison, carousel, avatar
+- **Navigate or organize** — page, breadcrumb, tabs, details, tree, divider, card, tag, badge
+- **Overlay or float** — dialog, drawer, tooltip, popover, dropdown
+
+---
+
+## Pick one from a set
+
+The user is choosing one value from a set of options.
+
+| You need…                                     | Use                                  |
+| --------------------------------------------- | ------------------------------------ |
+| 2–5 visible options, all related              | `<cs-radio-group>` with `<cs-radio>` |
+| More options, dropdown form field             | `<cs-select>` with `<cs-option>`     |
+| Yes / no toggle that takes effect immediately | `<cs-switch>`                        |
+| Yes / no in a form (submitted later)          | `<cs-checkbox>`                      |
+| A numeric value within a continuous range     | `<cs-slider>`                        |
+| A star rating                                 | `<cs-rating>`                        |
+| A color                                       | `<cs-color-picker>`                  |
+
+**`<cs-dropdown>` is not for picking a value.** `<cs-dropdown>` is for a **menu of actions** (think: a
+"More…" button that opens a list of commands). For picking a value from a list, use `<cs-select>`. This
+is the single most common confusion in the catalog.
+
+**Switch vs. checkbox.** Switch = instant-apply setting ("notifications on / off"). Checkbox = form
+field submitted later ("I accept the terms"). If toggling the control should immediately change
+something, it's a switch.
+
+---
+
+## Pick many
+
+Multi-selection from a set.
+
+| You need…                                 | Use                                            |
+| ----------------------------------------- | ---------------------------------------------- |
+| A small set of independent options        | Multiple `<cs-checkbox>` elements              |
+| Many options in a multi-select dropdown   | `<cs-select multiple>`                         |
+| Removable chip / tag selections           | `<cs-tag with-remove>` (manage your own state) |
+
+---
+
+## Trigger an action
+
+The user clicks or taps to make something happen.
+
+| You need…                                    | Use                                                 |
+| -------------------------------------------- | --------------------------------------------------- |
+| Primary call-to-action                       | `<cs-button variant="brand">`                       |
+| Secondary action                             | `<cs-button appearance="plain">`                    |
+| Destructive action                           | `<cs-button variant="danger">`                      |
+| Copy text to clipboard                       | `<cs-copy-button>`                                  |
+| A row of related buttons (segmented choices) | `<cs-button-group>` with `<cs-button>` children     |
+| Open a menu of commands                      | `<cs-dropdown>` with `<cs-dropdown-item>`           |
+| Switch between sections inline               | `<cs-tab-group>` with `<cs-tab>` + `<cs-tab-panel>` |
+
+**Single primary action per view.** If a view has more than one `variant="brand"` button, pick the most
+important one and demote the rest to `appearance="plain"` or `appearance="outlined"`. A wall of brand
+buttons reads as no primary action at all.
+
+---
+
+## Show feedback or status
+
+Non-interactive output telling the user something.
+
+| You need…                                                  | Use                                                                       |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Persistent inline message (info, success, warning, danger) | `<cs-callout>` with a `variant`                                           |
+| Brief ephemeral notification                               | `<cs-toast-item>` inside `<cs-toast>`                           |
+| Compact status indicator (number, "NEW", state)            | `<cs-badge>`                                                              |
+| Loading, duration unknown                                  | `<cs-spinner>`                                                            |
+| Loading, with progress                                     | `<cs-progress-bar>` (horizontal) or `<cs-progress-ring>` (compact circle) |
+| Placeholder while content loads                            | `<cs-skeleton>`                                                           |
+| Hover hint on a target                                     | `<cs-tooltip>`                                                            |
+| Larger contextual popup with rich content                  | `<cs-popover>`                                                            |
+
+**Callout vs. toast.** Callout = persistent, sits in the layout (e.g. a form error, an info panel). Toast
+= ephemeral, floats over the layout briefly (e.g. "Saved!" after a successful save). If the user might
+miss it on a glance, it's a callout.
+
+**Tooltip vs. popover.** Tooltip = text-only hint, automatic on hover / focus. Popover = arbitrary rich
+content, click to open. If you need anything beyond a short string, it's a popover.
+
+---
+
+## Capture input
+
+The user types or uploads.
+
+| You need…                                      | Use                                                          |
+| ---------------------------------------------- | ------------------------------------------------------------ |
+| Single-line text (incl. email, password, etc.) | `<cs-input>` with the appropriate `type`                     |
+| A number with stepper buttons                  | `<cs-number-input>` (richer than `<cs-input type="number">`) |
+| Multi-line text                                | `<cs-textarea>`                                              |
+| A color value                                  | `<cs-color-picker>`                                          |
+
+Use a `<form>` and the [form controls reference](form-controls.md) for validation patterns and form
+association behavior.
+
+---
+
+## Show data
+
+Read-only data display.
+
+| You need…                                         | Use                                                                                      |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Format a number with locale-aware rules           | `<cs-format-number>`                                                                     |
+| Format a date with locale-aware rules             | `<cs-format-date>`                                                                       |
+| Format a byte count                               | `<cs-format-bytes>`                                                                      |
+| Show a time as "5 minutes ago" (relative, live)   | `<cs-relative-time>`                                                                     |
+| A QR code                                         | `<cs-qr-code>`                                                                           |
+| Side-by-side image comparison                     | `<cs-comparison>`                                                                        |
+| A carousel / slideshow                            | `<cs-carousel>` with `<cs-carousel-item>`                                                |
+| An iframe with zoom controls                      | `<cs-zoomable-frame>`                                                                    |
+| A user avatar                                     | `<cs-avatar>`                                                                            |
+| An animation                                      | `<cs-animation>`                                                                         |
+| Markdown content rendered inline                  | `<cs-markdown>`                                                                          |
+| Include external HTML                             | `<cs-include>`                                                                           |
+
+---
+
+## Navigate or organize
+
+Structuring content or moving between views.
+
+| You need…                                            | Use                                                 |
+| ---------------------------------------------------- | --------------------------------------------------- |
+| The page-level frame (header, sidebar, main, footer) | `<cs-page>` — see the `cornerstone-design` skill     |
+| Breadcrumb trail                                     | `<cs-breadcrumb>` with `<cs-breadcrumb-item>`       |
+| Switch between sections inline                       | `<cs-tab-group>` with `<cs-tab>` + `<cs-tab-panel>` |
+| Expandable details disclosure                        | `<cs-details>`                                      |
+| Tree navigation (hierarchical lists)                 | `<cs-tree>` with `<cs-tree-item>`                   |
+| Visual separator between sections                    | `<cs-divider>`                                      |
+| Group of related content as a card                   | `<cs-card>`                                         |
+| Inline label (interactive)                           | `<cs-tag>` — removable, supports actions            |
+| Inline status indicator (non-interactive)            | `<cs-badge>` — small status pill                    |
+
+**Tag vs. badge.** Tag = interactive label (filter chip, removable selection, clickable category). Badge
+= small status indicator (count, "NEW", state). If the user can interact with it, it's a tag.
+
+---
+
+## Overlay or float
+
+Content that sits above the page.
+
+| You need…                                      | Use                                       |
+| ---------------------------------------------- | ----------------------------------------- |
+| Modal dialog (blocks page)                     | `<cs-dialog>`                             |
+| Side panel (non-blocking)                      | `<cs-drawer>`                             |
+| Floating tooltip (hover / focus)               | `<cs-tooltip>`                            |
+| Floating popover (click to open, rich content) | `<cs-popover>`                            |
+| Dropdown menu of actions                       | `<cs-dropdown>` with `<cs-dropdown-item>` |
+
+**Dialog vs. drawer.** Dialog = blocks the page (confirmations, focused tasks). Drawer = slides in
+alongside (settings panels, secondary nav). If the user must respond before continuing, it's a dialog.
+
+---
+
+## When the right component doesn't exist
+
+If nothing in the catalog matches what you need, before hand-rolling check:
+
+- **Is it really a component, or is it a section pattern?** Sections compose from existing components and
+  utility classes. See the `cornerstone-design` skill's `patterns.md` for ready-made section recipes.
+- **Could the layout utilities solve it?** `cs-stack`, `cs-cluster`, `cs-grid`, `cs-flank`, `cs-split`,
+  `cs-frame` cover most layout needs without a component.
+- **Could a `<cs-card>`, `<cs-callout>`, or `<cs-tag>` plus a few utility classes get you there?**
+
+When you genuinely need custom CSS to extend the system, follow the **Custom CSS playbook** in the
+`cornerstone-design` skill's `composition.md` (semantic tokens, `*-on-*` pairings for contrast,
+`loud` / `normal` / `quiet` as a contrast lever) so your additions stay themed, dark-mode-safe, and
+accessible.
+
+---
+
+## When nothing fits
+
+Cornerstone Components ships 70 components, and no catalog covers every need. When none of the tables
+above answer the question, compose from primitives rather than reaching for a component that does not
+exist — the layout utilities (`cs-stack`, `cs-cluster`, `cs-grid`) plus a `<cs-card>` or `<cs-callout>`
+cover most gaps. See `composition.md` in the `cornerstone-design` skill.