@cruglobal/cornerstone-components 0.1.0

package/dist/bundled/skills/cornerstone/references/localization.md

@@ -0,0 +1,133 @@
+# Localization
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/localization
+
+Components can be localized by importing the appropriate translation file and setting the desired [`lang`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) and/or [`dir`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) attributes on the `<html>` element. Here's an example that renders Cornerstone components in Spanish.
+
+```html
+<html lang="es">
+  <head>
+    <script type="module" src="/path/to/cornerstone/translations/es.js"></script>
+  </head>
+
+  <body>
+    ...
+  </body>
+</html>
+```
+
+Through the magic of a mutation observer, changing the `lang` attribute will automatically update all localized components to use the new locale.
+
+## Available Translations
+
+Cornerstone ships with a number of translations, one file per language in `src/translations`. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation.
+
+You can import translations using the following syntax, where `<code>` is replaced with any language code shown above.
+
+```js
+import '/dist/translations/<code>.js';
+```
+
+You do not need to load translations up front. You can import them dynamically even after updating the `lang` attribute. Once a translation is registered, localized components will update automatically.
+
+```js
+// Same as setting <html lang="de">
+document.documentElement.lang = 'de';
+
+// Import the translation
+import('/translations/<code>.js');
+```
+
+### Translation Resolution
+
+The locale set by `<html lang="...">` is the default locale for the document. If a country code is provided, e.g. `es-PE` for Peruvian Spanish, the localization library will resolve it like this:
+
+1. Look for `es-PE`
+2. Look for `es`
+3. Fall back to `en`
+
+Cornerstone uses English as a fallback to provide a better experience than rendering nothing or throwing an error.
+
+### Submitting New Translations or Improvements
+
+Translations live in `src/translations`, one file per language. Add or correct one there and open a pull request.
+
+Regional translations are welcome. If a German translation (`de`) exists, a German (Switzerland) (`de-CH`) translation on top of it is perfectly reasonable.
+
+> **Info**
+>
+> Cornerstone provides a localization mechanism for component internals. This is not designed to be used as localization tool for your entire application. You should use a more appropriate tool such as [i18next](https://www.i18next.com/) if you need to localize content in your app.
+
+## Multiple Locales per Page
+
+You can use a different locale for an individual component by setting its `lang` and/or `dir` attributes. Here's a contrived example to demonstrate.
+
+```html
+<html lang="es">
+  ...
+
+  <body>
+    <cs-button><!-- Spanish --></cs-button>
+    <cs-button lang="ru"><!-- Russian --></cs-button>
+  </body>
+</html>
+```
+
+For performance reasons, the `lang` and `dir` attributes must be on the component itself, not on an ancestor element.
+
+```html
+<html lang="es">
+  ...
+
+  <body>
+    <div lang="ru">
+      <cs-button><!-- still in Spanish --></cs-button>
+    </div>
+  </body>
+</html>
+```
+
+This limitation exists because there's no efficient way to determine the current locale of a given element in a DOM tree. I consider this a gap in the platform and [I've proposed a couple properties](https://github.com/whatwg/html/issues/7039) to make this possible.
+
+## Creating Your Own Translations
+
+You can provide your own translations if you have specific needs or if you don't want to wait for a translation to land upstream. The easiest way to do this is to copy `src/translations/en.ts` into your own project and translate the terms inside. When your translation is done, you can import it and use it just like a built-in translation.
+
+Let's create a Spanish translation as an example. The following assumes you're using TypeScript, but you can also create translations with regular JavaScript.
+
+```ts
+import { registerTranslation } from 'path/to/cornerstone.js';
+import type { Translation } from 'path/to/cornerstone.js';
+
+const translation: Translation = {
+  $code: 'es',
+  $name: 'Español',
+  $dir: 'ltr',
+
+  term1: '...',
+  term2: '...',
+  ...
+};
+
+registerTranslation(translation);
+
+export default translation;
+```
+
+Once your translation has been compiled to JavaScript, import it and activate it like this.
+
+```html
+<html lang="es">
+  <head>
+    <script type="module" src="/path/to/es.js"></script>
+  </head>
+
+  <body>
+    ...
+  </body>
+</html>
+```
+
+> **Info**
+>
+> If your translation isn't working, make sure you're using the same localize module when importing `registerTranslation`. If you're using a different module, your translation won't be recognized.

package/dist/bundled/skills/cornerstone/references/support.md

@@ -0,0 +1,10 @@
+# Support
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/resources/support
+
+## Getting Help
+
+### GitHub
+
+- **Issues**: Report bugs with clear reproduction steps
+  https://github.com/CruGlobal/cornerstone-design-system/issues

package/dist/bundled/skills/cornerstone/references/themes.md

@@ -0,0 +1,55 @@
+# Themes & Color Palettes
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/themes
+
+## Applying Themes
+
+Cru's theme is the default and needs no class — importing the library applies it. The class form
+exists so a theme can be scoped to a subtree, or so a second theme can be switched to:
+
+```html
+<html class="cs-theme-cru cs-light">
+```
+
+For npm/CDN users, `cornerstone.css` already imports Cru's theme. Import a stylesheet only to
+choose a different one:
+
+```js
+import '@cruglobal/cornerstone-components/styles/themes/default.css';
+```
+
+## Themes
+
+| Theme | Description |
+|-------|-------------|
+| **Cru** | The default. Cru's brand, generated from its key colours on a luminance ladder |
+| **Default** | An unbranded reference theme, for a product that is not using Cru's brand |
+
+New brands are generated rather than picked from a list — see `tools/palette.mjs`.
+
+## Color Palettes
+
+A palette provides the hue ramps a theme's roles read, each on a scale of 11 steps
+(`05`–`95`). Cru's carries 18 hues; the reference palette carries 10.
+
+- **Cru** - Cru's brand hues, generated
+- **Default** - The reference hues
+
+## Applying Palettes
+
+Each theme imports its own palette, so there is normally nothing to apply. The class form scopes
+one to a subtree:
+
+```html
+<html class="cs-palette-default">
+```
+
+CSS variables follow the pattern `--cs-color-{hue}-{tint}`:
+
+```css
+.my-element {
+  color: var(--cs-color-blue-60);
+  background: var(--cs-color-gray-10);
+}
+```
+

package/dist/bundled/skills/cornerstone/references/theming-overview.md

@@ -0,0 +1,114 @@
+# Theming
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/theming-overview
+
+Cornerstone themes apply a cohesive look and feel across the entire library, built from stackable layers — a [theme](https://cruglobal.github.io/cornerstone-design-system/themes), a [color palette](https://cruglobal.github.io/cornerstone-design-system/color-palettes), [variants](https://cruglobal.github.io/cornerstone-design-system/tokens/color#variant-colors), and a light or dark color scheme — that you mix and match with classes on the `<html>` element.
+
+> **Info**
+>
+> **Try it live!** Use the <cs-tag class="tag-ui" appearance="outlined"><cs-icon name="palette"></cs-icon></cs-tag> Theme and <cs-tag class="tag-ui" appearance="outlined"><cs-icon name="sunny"></cs-icon></cs-tag> Color Scheme selectors in this site's header to preview themes or switch light/dark modes.
+
+## Key Concepts
+
+### Themes
+
+`.cs-theme-{name}`
+
+A theme is the overall look — fonts, borders, space, shadows, and how each [variant](https://cruglobal.github.io/cornerstone-design-system/tokens/color#variant-colors) gets used across components. Two themes can share a [palette](https://cruglobal.github.io/cornerstone-design-system/color-palettes) and [variants](https://cruglobal.github.io/cornerstone-design-system/tokens/color#variant-colors) and still feel completely different. Themes ship with a default palette and may include custom CSS overrides for individual components.
+
+Your theme is determined by `class="cs-theme-{name}"` on the `<html>` element. If no class is specified, the default theme is used.
+
+<cs-button appearance="outlined" size="s" href="/themes">
+  Browse Built-in Themes
+  <cs-icon slot="end" name="arrow_forward"></cs-icon>
+</cs-button>
+
+### Color Palettes
+
+`.cs-palette-{name}`
+
+A color palette is the full set of 10 hues — red, orange, yellow, green, cyan, blue, indigo, purple, pink, and gray — each with 11 tints from `05` (darkest) to `95` (lightest), all available as [color design tokens](https://cruglobal.github.io/cornerstone-design-system/tokens/color).
+
+Each palette has its own hue shifts and chroma, so swapping palettes changes the entire feel of your project — especially alongside a [theme](https://cruglobal.github.io/cornerstone-design-system/themes) and [variant colors](https://cruglobal.github.io/cornerstone-design-system/tokens/color#variant-colors). Your palette is determined by `class="cs-palette-{name}"` on the `<html>` element; if no class is specified, the default palette is used.
+
+<cs-button appearance="outlined" size="s" href="/color-palettes">
+  Browse All Palettes
+  <cs-icon slot="end" name="arrow_forward"></cs-icon>
+</cs-button>
+
+### Variants
+
+`.cs-{variant}-{hue}`
+
+Variants assign palette hues to semantic roles — `brand`, `neutral`, `success`, `warning`, and `danger` among them — so components like buttons and callouts can convey meaning through color. Any hue from your palette can be assigned to any variant with `class="cs-{variant}-{hue}"`. Apply the class to the `<html>` element to set variants globally, to a wrapper to scope them to one section, or to a single component to override just that element. For deeper customization, [override the `--cs-color-{variant}-*` tokens](https://cruglobal.github.io/cornerstone-design-system/customizing#customizing-with-css) in your own CSS.
+
+<cs-button appearance="outlined" size="s" href="/tokens/color#variant-colors">
+  See Variant Tokens
+  <cs-icon slot="end" name="arrow_forward"></cs-icon>
+</cs-button>
+
+### Light and Dark Mode
+
+<span class="cs-cluster">`.cs-light` `.cs-dark`</span>
+
+Every theme is designed to adapt to light and dark mode. Light mode applies by default; apply `class="cs-light"` or `class="cs-dark"` to set the color scheme on the page or on any section. Because the classes cascade, a dark page can hold a light section, and the components inside each pick up the scheme around them.
+
+```html
+<div class="cs-grid">
+  <cs-card class="cs-light">
+    <div slot="header" class="cs-split cs-color-text-quiet">
+      <h4 class="cs-heading-s">Light</h4>
+      <cs-icon name="sunny"></cs-icon>
+    </div>
+    <div class="cs-stack">
+      <cs-input label="# of Waffles" type="number" value="3"></cs-input>
+      <cs-select label="Toppings" multiple value="jelly-beans">
+        <cs-option value="whipped-cream">Whipped cream</cs-option>
+        <cs-option value="hershey">Hershey's Kisses</cs-option>
+        <cs-option value="jelly-beans">Jelly beans</cs-option>
+      </cs-select>
+      <cs-button appearance="filled" variant="brand">
+        <cs-icon slot="start" name="grid_on"></cs-icon>
+        Make Waffles
+      </cs-button>
+    </div>
+  </cs-card>
+
+  <cs-card class="cs-dark">
+    <div slot="header" class="cs-split cs-color-text-quiet">
+      <h4 class="cs-heading-s">Dark</h4>
+      <cs-icon name="dark_mode"></cs-icon>
+    </div>
+    <div class="cs-stack">
+      <cs-input label="# of Waffles" type="number" value="3"></cs-input>
+      <cs-select label="Toppings" multiple value="jelly-beans">
+        <cs-option value="whipped-cream">Whipped cream</cs-option>
+        <cs-option value="hershey">Hershey's Kisses</cs-option>
+        <cs-option value="jelly-beans">Jelly beans</cs-option>
+      </cs-select>
+      <cs-button appearance="filled" variant="brand">
+        <cs-icon slot="start" name="grid_on"></cs-icon>
+        Make Waffles
+      </cs-button>
+    </div>
+  </cs-card>
+</div>
+```
+
+## Using Themes
+
+Load the theme's stylesheet, then put its class on the `<html>` element. The snippets below cover each way of loading it.
+
+## Creating Your Own
+
+You can build a custom theme with [custom CSS](https://cruglobal.github.io/cornerstone-design-system/customizing#customizing-with-css), overriding [design tokens](https://cruglobal.github.io/cornerstone-design-system/tokens) in your own stylesheet.
+
+## Quick Reference
+
+| Task                    | How To                                                                        | Learn More                                                 |
+| ----------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Change my brand color   | Add `class="cs-brand-{hue}"` to `<html>`                                       | [Changing Variants](https://cruglobal.github.io/cornerstone-design-system/tokens/color#changing-variant-colors)  |
+| Switch color palettes   | Load the palette stylesheet, then add `class="cs-palette-{name}"` to `<html>` | [Browse Palettes](https://cruglobal.github.io/cornerstone-design-system/color-palettes)                         |
+| Use a different theme   | Load the theme stylesheet, then add `class="cs-theme-{name}"` to `<html>`     | [Built-in Themes](https://cruglobal.github.io/cornerstone-design-system/themes)                                 |
+| Toggle dark mode        | Add `class="cs-dark"` to `<html>` (or any section)                            | [Light and Dark Mode](#light-and-dark-mode)                |
+| Override a single token | Define a `--cs-*` custom property associated with a [design token](https://cruglobal.github.io/cornerstone-design-system/tokens)   | [Customizing With CSS](https://cruglobal.github.io/cornerstone-design-system/customizing#customizing-with-css)   |

package/dist/bundled/skills/cornerstone/references/tokens/borders.md

@@ -0,0 +1,113 @@
+# Borders
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/tokens/borders
+
+<style>
+  .swatch {
+    border-color: var(--cs-color-neutral-border-normal);
+  }
+</style>
+
+Border tokens define the edges and corners of Cornerstone components. They use `rem` units so they scale with root font size. You can adjust individual tokens or use scale multipliers to change all widths or radii at once.
+
+## Border Style
+
+A single style token controls the line type used for all component borders throughout the library.
+
+<cs-scroller>
+  <table class="token-table cs-hover-rows">
+    <thead>
+      <tr><th>Custom Property</th><th>Description</th><th>Preview</th></tr>
+    </thead>
+    <tbody>
+      <tr id="token-cs-border-style">
+        <td class="token-name"><code>--cs-border-style</code></td>
+        <td>Standard border line style used across all components</td>
+        <td><div class="swatch" style="border-style: var(--cs-border-style)"></div></td>
+      </tr>
+    </tbody>
+  </table>
+</cs-scroller>
+
+## Border Width
+
+Border width tokens use `rem` units and are scaled by `--cs-border-width-scale`. Values below `1` make all borders thinner; values above `1` make them thicker.
+
+<cs-scroller>
+  <table class="token-table cs-hover-rows">
+    <thead>
+      <tr><th>Custom Property</th><th>Description</th><th>Preview</th></tr>
+    </thead>
+    <tbody>
+      <tr id="token-cs-border-width-scale">
+        <td class="token-name"><code>--cs-border-width-scale</code></td>
+        <td>Global multiplier for all border width calculations</td>
+        <td>—</td>
+      </tr>
+      <tr id="token-cs-border-width-s">
+        <td class="token-name"><code>--cs-border-width-s</code></td>
+        <td>Thin border, used for most component outlines</td>
+        <td><div class="swatch" style="border-width: var(--cs-border-width-s)"></div></td>
+      </tr>
+      <tr id="token-cs-border-width-m">
+        <td class="token-name"><code>--cs-border-width-m</code></td>
+        <td>Medium border, used for emphasized borders</td>
+        <td><div class="swatch" style="border-width: var(--cs-border-width-m)"></div></td>
+      </tr>
+      <tr id="token-cs-border-width-l">
+        <td class="token-name"><code>--cs-border-width-l</code></td>
+        <td>Thick border, used for prominent outlines</td>
+        <td><div class="swatch" style="border-width: var(--cs-border-width-l)"></div></td>
+      </tr>
+    </tbody>
+  </table>
+</cs-scroller>
+
+## Border Radius
+
+Border radius tokens control the corner rounding of components. Size-based tokens use `rem` units and scale with `--cs-border-radius-scale`. Values below `1` make corners sharper; values above `1` make them rounder. Shape tokens provide fixed shapes regardless of the scale.
+
+<cs-scroller>
+  <table class="token-table cs-hover-rows">
+    <thead>
+      <tr><th>Custom Property</th><th>Description</th><th>Preview</th></tr>
+    </thead>
+    <tbody>
+      <tr id="token-cs-border-radius-scale">
+        <td class="token-name"><code>--cs-border-radius-scale</code></td>
+        <td>Global multiplier for all border radius calculations</td>
+        <td>—</td>
+      </tr>
+      <tr id="token-cs-border-radius-s">
+        <td class="token-name"><code>--cs-border-radius-s</code></td>
+        <td>Small corner rounding, for compact components like badges and checkboxes</td>
+        <td><div class="swatch" style="border-radius: var(--cs-border-radius-s)"></div></td>
+      </tr>
+      <tr id="token-cs-border-radius-m">
+        <td class="token-name"><code>--cs-border-radius-m</code></td>
+        <td>Medium corner rounding, the default for most inputs and buttons</td>
+        <td><div class="swatch" style="border-radius: var(--cs-border-radius-m)"></div></td>
+      </tr>
+      <tr id="token-cs-border-radius-l">
+        <td class="token-name"><code>--cs-border-radius-l</code></td>
+        <td>Large corner rounding, for cards and panels</td>
+        <td><div class="swatch" style="border-radius: var(--cs-border-radius-l)"></div></td>
+      </tr>
+      <tr id="token-cs-border-radius-pill">
+        <td class="token-name"><code>--cs-border-radius-pill</code></td>
+        <td>Fully rounded ends, creating a pill shape regardless of element size</td>
+        <td><div class="swatch" style="border-radius: var(--cs-border-radius-pill)"></div></td>
+      </tr>
+      <tr id="token-cs-border-radius-circle">
+        <td class="token-name"><code>--cs-border-radius-circle</code></td>
+        <td>Perfectly circular shape; element must have a 1:1 aspect ratio</td>
+        <td><div class="swatch" style="aspect-ratio: 1 / 1; border-radius: var(--cs-border-radius-circle)"></div></td>
+      </tr>
+      <tr id="token-cs-border-radius-square">
+        <td class="token-name"><code>--cs-border-radius-square</code></td>
+        <td>No corner rounding; sharp, square corners</td>
+        <td><div class="swatch" style="border-radius: var(--cs-border-radius-square)"></div></td>
+      </tr>
+    </tbody>
+  </table>
+</cs-scroller>