@magentofullstackdev/hyperion-shared 0.0.0-stage → 0.9.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergiu Ro -- magentofullstackdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @magentofullstackdev/hyperion-shared
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared design tokens, Tailwind preset, and base Lit element / mixins for the
+[Hyperion](https://github.com/magentofullstackdev/hyperion) Magento 2 theme
+suite.
+
+This package is published as TypeScript / CSS source (a beta, `0.9.0-beta.x`,
+versioned with the suite). It has no build step: sibling packages
+(`@magentofullstackdev/hyperion-theme`, `@magentofullstackdev/hyperion-checkout`)
+consume it directly through their own bundler (Vite). Installing it does not
+install or activate anything in Magento; the storefront comes from the
+Composer packages, see
+[`docs/install.md`](https://github.com/magentofullstackdev/hyperion/blob/main/docs/install.md).
+
+## Install
+
+```bash
+npm install @magentofullstackdev/hyperion-shared
+```
+
+## Usage
+
+Tailwind preset:
+
+```ts
+// tailwind.config.ts
+import hyperionPreset from '@magentofullstackdev/hyperion-shared/tailwind/preset';
+
+export default {
+    presets: [hyperionPreset],
+    content: ['./src/**/*.{ts,tsx,js,html}'],
+};
+```
+
+Design tokens (CSS):
+
+```css
+/* your-theme.css */
+@import "@magentofullstackdev/hyperion-shared/tokens/index.css";
+```
+
+Base Lit element:
+
+```ts
+import { HyperionLightElement } from '@magentofullstackdev/hyperion-shared/lit';
+
+class MyComponent extends HyperionLightElement {
+    /* ... */
+}
+```
+
+## Exports
+
+| Subpath | Purpose |
+|---|---|
+| `.` | Barrel: `tailwindPreset`, base Lit element, mixins |
+| `./tailwind/preset` | Tailwind 3.x preset (semantic colours, spacing, typography) |
+| `./tokens/*` | Raw CSS custom properties (`colors.css`, `spacing.css`, `typography.css`, `index.css`) |
+| `./lit` / `./lit/*` | Base Lit element + mixins |
+| `./html` | HTML sanitizer (allowlist) used for cookie and response HTML |
+
+## Requirements
+
+A TypeScript-aware bundler (Vite, esbuild, webpack with `ts-loader`, etc.).
+This package ships `.ts` source, not pre-compiled JavaScript, so it cannot be
+loaded directly by Node.
+
+## Links
+
+- Website: <https://hyperionfront.dev>
+- Live demo: <https://demo.hyperionfront.dev>
+- Repository: <https://github.com/magentofullstackdev/hyperion>
+- Changelog: [`CHANGELOG.md`](https://github.com/magentofullstackdev/hyperion/blob/main/CHANGELOG.md) in the main repo
+- Issues: <https://github.com/magentofullstackdev/hyperion/issues>
+- Documentation: `docs/child-themes.md` in the main repo (design tokens, base element)
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@magentofullstackdev/hyperion-shared",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0-beta.2",
+  "description": "Shared design tokens, Tailwind preset, and base Lit element/mixins for the Hyperion Magento 2 theme suite. Consumed by @magentofullstackdev/hyperion-theme and @magentofullstackdev/hyperion-checkout.",
+  "license": "MIT",
+  "author": "Sergiu Ro <sergiu.ro@magentofullstack.dev>",
+  "homepage": "https://hyperionfront.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magentofullstackdev/hyperion.git",
+    "directory": "frontend/packages/shared"
+  },
+  "bugs": {
+    "url": "https://github.com/magentofullstackdev/hyperion/issues"
+  },
+  "keywords": [
+    "magento",
+    "magento2",
+    "hyperion",
+    "tailwind",
+    "tailwind-preset",
+    "lit",
+    "design-tokens",
+    "frontend"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tokens/*": "./src/tokens/*",
+    "./tailwind/preset": "./src/tailwind/preset.ts",
+    "./lit": "./src/lit/index.ts",
+    "./lit/*": "./src/lit/*",
+    "./html": "./src/html/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!src/**/__tests__",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tailwindcss/typography": "^0.5.19"
+  },
+  "peerDependencies": {
+    "lit": "^3.1.2",
+    "tailwindcss": "^3.4.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^6.15.0",
+    "@typescript-eslint/parser": "^6.15.0",
+    "eslint": "^8.56.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "echo \"@magentofullstackdev/hyperion-shared has no build step: consumed as TypeScript source by sibling workspaces\"",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.ts'"
+  }
 }

package/src/html/index.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sergiu Ro -- magentofullstackdev
+
+export {
+    sanitizeHtml,
+    sanitizeMessageHtml,
+    htmlToText,
+    RICH_TEXT_TAGS,
+    MESSAGE_TAGS,
+    MESSAGE_OPTIONS,
+} from './sanitize.js';
+export type { SanitizeOptions } from './sanitize.js';

package/src/html/sanitize.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sergiu Ro -- magentofullstackdev
+
+/**
+ * Allowlist HTML sanitizer for the few places where Magento hands the
+ * storefront display HTML: session messages (the `mage-messages` cookie)
+ * and admin-authored rich text in the checkout.
+ *
+ * Not a general-purpose sanitizer. The input is parsed into an inert
+ * document (DOMParser: no script runs, no resource loads, no event
+ * handler fires) and the output is rebuilt node by node from the
+ * allowlist, so nothing that is not named here can reach the page.
+ * Attributes are dropped, except the listed ones on links.
+ */
+
+export interface SanitizeOptions {
+    /** Element names kept in the output. Anything else is unwrapped to its children. */
+    tags?: readonly string[];
+    /** Attributes kept on `<a>`. */
+    linkAttributes?: readonly string[];
+    /** URL schemes (with the colon) a link may point to; relative links resolve to the page's own. */
+    linkProtocols?: readonly string[];
+}
+
+/** Inline formatting and lists, as Magento's rich-text editor emits them. */
+export const RICH_TEXT_TAGS: readonly string[] = [
+    'p', 'br', 'strong', 'em', 'b', 'i', 'u',
+    'ul', 'ol', 'li',
+    'a', 'span', 'div',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+];
+
+/** What core's message component allows (Magento_Theme/js/view/messages.js). */
+export const MESSAGE_TAGS: readonly string[] = ['div', 'span', 'b', 'strong', 'i', 'em', 'u', 'a'];
+
+export const MESSAGE_OPTIONS: SanitizeOptions = {
+    tags: MESSAGE_TAGS,
+    linkAttributes: ['href'],
+    linkProtocols: ['http:', 'https:'],
+};
+
+const DEFAULT_LINK_ATTRIBUTES: readonly string[] = ['href', 'title', 'rel', 'target'];
+const DEFAULT_LINK_PROTOCOLS: readonly string[] = ['http:', 'https:', 'mailto:', 'tel:'];
+
+/** Elements whose content is code or foreign markup, never text to show. */
+const DISCARDED_TAGS = new Set([
+    'script', 'style', 'template', 'noscript', 'iframe', 'object', 'embed',
+    'svg', 'math', 'textarea', 'title', 'head',
+]);
+
+interface Rules {
+    tags: Set<string>;
+    linkAttributes: Set<string>;
+    linkProtocols: Set<string>;
+}
+
+function parse(input: string): { doc: Document; root: Element | null } {
+    const doc = new DOMParser().parseFromString(`<div>${input}</div>`, 'text/html');
+    return { doc, root: doc.body.firstElementChild };
+}
+
+/**
+ * The scheme is decided by the URL parser, not by a pattern: it is what
+ * the browser will use and it is immune to case and whitespace tricks.
+ */
+function isSafeHref(href: string, protocols: Set<string>): boolean {
+    try {
+        return protocols.has(new URL(href, window.location.origin).protocol);
+    } catch {
+        return false;
+    }
+}
+
+function cleanLink(source: Element, clean: Element, rules: Rules): void {
+    for (const attr of Array.from(source.attributes)) {
+        const name = attr.name.toLowerCase();
+        if (rules.linkAttributes.has(name)) {
+            clean.setAttribute(name, attr.value);
+        }
+    }
+    const href = clean.getAttribute('href') ?? '';
+    if (href && !isSafeHref(href.trim(), rules.linkProtocols)) {
+        clean.removeAttribute('href');
+    }
+    const target = clean.getAttribute('target');
+    if (target !== null && target !== '_blank') {
+        clean.removeAttribute('target');
+    }
+    const safeHref = clean.getAttribute('href') ?? '';
+    if (/^https?:/i.test(safeHref) || clean.getAttribute('target') === '_blank') {
+        clean.setAttribute('rel', 'noopener noreferrer');
+    }
+}
+
+function appendClean(doc: Document, source: Node, target: Node, rules: Rules): void {
+    source.childNodes.forEach((child) => {
+        if (child.nodeType === 3) {
+            target.appendChild(doc.createTextNode(child.textContent ?? ''));
+            return;
+        }
+        if (child.nodeType !== 1) {
+            return;
+        }
+        const element = child as Element;
+        const tag = element.tagName.toLowerCase();
+        if (DISCARDED_TAGS.has(tag)) {
+            return;
+        }
+        if (!rules.tags.has(tag)) {
+            appendClean(doc, element, target, rules);
+            return;
+        }
+        const clean = doc.createElement(tag);
+        if (tag === 'a') {
+            cleanLink(element, clean, rules);
+        }
+        appendClean(doc, element, clean, rules);
+        target.appendChild(clean);
+    });
+}
+
+/**
+ * HTML that holds only the allowed elements; safe to assign to `innerHTML`.
+ */
+export function sanitizeHtml(input: string, options: SanitizeOptions = {}): string {
+    const { doc, root } = parse(String(input ?? ''));
+    if (!root) return '';
+    const out = doc.createElement('div');
+    appendClean(doc, root, out, {
+        tags: new Set(options.tags ?? RICH_TEXT_TAGS),
+        linkAttributes: new Set(options.linkAttributes ?? DEFAULT_LINK_ATTRIBUTES),
+        linkProtocols: new Set(options.linkProtocols ?? DEFAULT_LINK_PROTOCOLS),
+    });
+    return out.innerHTML;
+}
+
+/**
+ * Session message from Magento as HTML: core's message allowlist, links
+ * to http(s) and relative targets only.
+ */
+export function sanitizeMessageHtml(input: string): string {
+    return sanitizeHtml(input, MESSAGE_OPTIONS);
+}
+
+/**
+ * Plain text of a value Magento hands out as display HTML (messages, cart
+ * item option values: escaped text, list entries joined with `<br />`,
+ * bundle selections with the price in a `<span>`). Line breaks become `, `.
+ */
+export function htmlToText(input: string): string {
+    const { doc, root } = parse(String(input ?? ''));
+    if (!root) return '';
+    root.querySelectorAll(Array.from(DISCARDED_TAGS).join(',')).forEach((element) => element.remove());
+    root.querySelectorAll('br').forEach((br) => br.replaceWith(doc.createTextNode(', ')));
+    return (root.textContent ?? '').replace(/\s+/g, ' ').replace(/ ,/g, ',').trim();
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sergiu Ro -- magentofullstackdev
+
+/**
+ * @magentofullstackdev/hyperion-shared barrel export.
+ *
+ * Re-exports the public API surface of the shared workspace package:
+ * Tailwind preset, base Lit element, mixins, HTML sanitizer. Design tokens (CSS) are
+ * consumed via direct CSS imports -- see `./tokens/*` exports in
+ * package.json.
+ */
+export { default as tailwindPreset } from './tailwind/preset.js';
+export * from './lit/index.js';
+export * from './html/index.js';

package/src/lit/HyperionLightElement.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sergiu Ro -- magentofullstackdev
+
+/**
+ * Base Lit element for Hyperion components that need light-DOM rendering.
+ *
+ * Several Hyperion components -- every form-bearing component in the
+ * checkout, the account-nav enhancer, the coupon form,
+ * etc. -- must render to light DOM so:
+ *
+ *   * Tailwind utility classes from the page's stylesheet cascade in,
+ *   * Browser autofill and password managers (1Password, Bitwarden,
+ *     browser built-ins) can introspect the inputs,
+ *   * `form.checkValidity()` and the Constraint Validation API cross
+ *     the element boundary reliably.
+ *
+ * This base class collapses the boilerplate `createRenderRoot() { return this; }`
+ * that every such component would otherwise duplicate. Components that
+ * need shadow DOM (sliders, dropdowns, the mini-cart drawer) should
+ * extend `LitElement` directly -- they don't need this class.
+ */
+import { LitElement } from 'lit';
+
+export class HyperionLightElement extends LitElement {
+    public override createRenderRoot(): HTMLElement {
+        return this;
+    }
+}
+
+export type HyperionLightElementBase = typeof HyperionLightElement;

package/src/lit/index.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sergiu Ro -- magentofullstackdev
+
+/**
+ * @magentofullstackdev/hyperion-shared/lit barrel.
+ *
+ * Re-exports the Lit primitives shared across @magentofullstackdev/hyperion-theme
+ * and @magentofullstackdev/hyperion-checkout: a base element with the suite-wide
+ * light-DOM render-root convention, and mixins for SignalWatcher
+ * integration.
+ */
+export { HyperionLightElement } from './HyperionLightElement.js';
+export type { HyperionLightElementBase } from './HyperionLightElement.js';

package/src/tailwind/preset.ts

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sergiu Ro -- magentofullstackdev
+
+/**
+ * @magentofullstackdev/hyperion-shared/tailwind/preset
+ *
+ * Single source of truth for the Hyperion suite's Tailwind palette
+ * mapping. Both @magentofullstackdev/hyperion-theme and @magentofullstackdev/hyperion-checkout
+ * extend this preset (`presets: [hyperionPreset]`) so a `bg-primary` /
+ * `text-on-primary` / `border-subtle` class resolves identically in
+ * theme markup and checkout markup.
+ *
+ * Every semantic color token is mapped to a CSS Custom Property
+ * declared in `@magentofullstackdev/hyperion-shared/tokens/colors.css` using the
+ * `rgb(var(--color-*) / <alpha-value>)` syntax that lets Tailwind's
+ * opacity-modifier classes (e.g. `bg-primary/50`) work.
+ *
+ * `primary` and `primary-hover` are independent tokens so that
+ * `ring-primary` (focus-visibility) and `bg-primary-hover` (hover)
+ * resolve to separate CSS variables -- satisfies WCAG 2.1 AA
+ * focus-visibility overridability.
+ *
+ * The `content` array is intentionally EMPTY here -- each consuming
+ * package declares its own `content` glob in its `tailwind.config.ts`
+ * because the paths are package-specific.
+ */
+import typography from '@tailwindcss/typography';
+import type { Config } from 'tailwindcss';
+
+const preset: Partial<Config> = {
+    theme: {
+        extend: {
+            colors: {
+                primary: 'rgb(var(--color-primary) / <alpha-value>)',
+                'primary-hover': 'rgb(var(--color-primary-hover) / <alpha-value>)',
+                secondary: 'rgb(var(--color-secondary) / <alpha-value>)',
+                accent: 'rgb(var(--color-accent) / <alpha-value>)',
+                surface: 'rgb(var(--color-surface) / <alpha-value>)',
+                'surface-raised': 'rgb(var(--color-surface-raised) / <alpha-value>)',
+                'on-primary': 'rgb(var(--color-on-primary) / <alpha-value>)',
+                'on-secondary': 'rgb(var(--color-on-secondary) / <alpha-value>)',
+                muted: 'rgb(var(--color-muted) / <alpha-value>)',
+                subtle: 'rgb(var(--color-subtle) / <alpha-value>)',
+                error: 'rgb(var(--color-error) / <alpha-value>)',
+                'on-error': 'rgb(var(--color-on-error) / <alpha-value>)',
+                'error-strong': 'rgb(var(--color-error-strong) / <alpha-value>)',
+                success: 'rgb(var(--color-success) / <alpha-value>)',
+                'on-success': 'rgb(var(--color-on-success) / <alpha-value>)',
+                'success-strong': 'rgb(var(--color-success-strong) / <alpha-value>)',
+                warning: 'rgb(var(--color-warning) / <alpha-value>)',
+                'warning-strong': 'rgb(var(--color-warning-strong) / <alpha-value>)',
+                'on-warning': 'rgb(var(--color-on-warning) / <alpha-value>)',
+                info: 'rgb(var(--color-info) / <alpha-value>)',
+                'on-info': 'rgb(var(--color-on-info) / <alpha-value>)',
+                inverted: 'rgb(var(--color-surface-inverted) / <alpha-value>)',
+                'on-inverted':         'rgb(var(--color-on-inverted) / <alpha-value>)',
+                'on-inverted-muted':   'rgb(var(--color-on-inverted-muted) / <alpha-value>)',
+                'subtle-inverted':     'rgb(var(--color-subtle-inverted) / <alpha-value>)',
+                'price-sale': 'rgb(var(--color-price-sale) / <alpha-value>)',
+                // Extended tokens: semantic replacements for the banned palette classes.
+                'surface-sunken':  'rgb(var(--color-surface-sunken) / <alpha-value>)',
+                'surface-overlay': 'rgb(var(--color-surface-overlay) / <alpha-value>)',
+                'text-default':    'rgb(var(--color-text-default) / <alpha-value>)',
+                'text-secondary':  'rgb(var(--color-text-secondary) / <alpha-value>)',
+                'text-tertiary':   'rgb(var(--color-text-tertiary) / <alpha-value>)',
+                'border-default':  'rgb(var(--color-border-default) / <alpha-value>)',
+                divider: 'rgb(var(--color-divider) / <alpha-value>)',
+                'error-hover':     'rgb(var(--color-error-hover) / <alpha-value>)',
+                'error-active':    'rgb(var(--color-error-active) / <alpha-value>)',
+                'success-subtle':  'rgb(var(--color-success-subtle) / <alpha-value>)',
+                'warning-light':   'rgb(var(--color-warning-light) / <alpha-value>)',
+                'focus-ring':      'rgb(var(--color-focus-ring) / <alpha-value>)',
+                // Checkout aliases -- kept in the preset so existing
+                // checkout component class names (`bg-brand`, `text-on-brand`)
+                // keep resolving without a per-component rewrite.
+                brand: 'rgb(var(--checkout-color-brand) / <alpha-value>)',
+                'on-brand': 'rgb(var(--checkout-color-on-brand) / <alpha-value>)',
+                danger: 'rgb(var(--checkout-color-danger) / <alpha-value>)',
+                'on-danger': 'rgb(var(--checkout-color-on-danger) / <alpha-value>)',
+            },
+            typography: () => ({
+                DEFAULT: {
+                    css: {
+                        '--tw-prose-body':          'rgb(var(--color-secondary))',
+                        '--tw-prose-headings':      'rgb(var(--color-secondary))',
+                        '--tw-prose-lead':          'rgb(var(--color-muted))',
+                        '--tw-prose-links':         'rgb(var(--color-primary))',
+                        '--tw-prose-bold':          'rgb(var(--color-secondary))',
+                        '--tw-prose-counters':      'rgb(var(--color-muted))',
+                        '--tw-prose-bullets':       'rgb(var(--color-subtle))',
+                        '--tw-prose-hr':            'rgb(var(--color-subtle))',
+                        '--tw-prose-quotes':        'rgb(var(--color-secondary))',
+                        '--tw-prose-quote-borders': 'rgb(var(--color-primary))',
+                        '--tw-prose-captions':      'rgb(var(--color-muted))',
+                        '--tw-prose-code':          'rgb(var(--color-secondary))',
+                        '--tw-prose-pre-code':      'rgb(var(--color-on-inverted))',
+                        '--tw-prose-pre-bg':        'rgb(var(--color-surface-inverted))',
+                        '--tw-prose-th-borders':    'rgb(var(--color-subtle))',
+                        '--tw-prose-td-borders':    'rgb(var(--color-subtle))',
+                        maxWidth: 'none',
+                        a: {
+                            fontWeight: '500',
+                            textDecoration: 'underline',
+                            textUnderlineOffset: '2px',
+                            '&:hover': {
+                                color: 'rgb(var(--color-primary-hover))',
+                            },
+                        },
+                        'h1, h2, h3, h4': {
+                            fontWeight: '700',
+                            letterSpacing: '-0.01em',
+                        },
+                    },
+                },
+            }),
+        },
+    },
+    plugins: [typography],
+};
+
+export default preset;

package/src/tokens/colors.css

@@ -0,0 +1,105 @@
+/* SPDX-License-Identifier: MIT */
+/* Copyright (c) 2026 Sergiu Ro -- magentofullstackdev */
+
+/*
+ * @magentofullstackdev/hyperion-shared -- semantic color tokens.
+ *
+ * Single source of truth for the Hyperion suite's palette. Both
+ * @magentofullstackdev/hyperion-theme and @magentofullstackdev/hyperion-checkout import this
+ * file (via `@magentofullstackdev/hyperion-shared/tokens/colors.css`) so a single rebrand
+ * propagates everywhere.
+ *
+ * Values MUST be raw RGB channel triplets as space-separated integers
+ * (e.g. `37 99 235`) -- never hex, never `rgb()` wrappers. This is the
+ * only format that lets Tailwind's `rgb(var(--color-*) / <alpha-value>)`
+ * mapping produce valid CSS for opacity-modifier classes such as
+ * `bg-primary/50`.
+ *
+ * Child themes override these declarations in their own `_theme.css`
+ * (loaded after this file in the cascade) -- see THEMING_GUIDE.md.
+ */
+:root {
+    /* --- Primary brand color -- buttons, links, active states, focus rings --- */
+    --color-primary: 37 99 235; /* #2563eb */
+    --color-primary-hover: 29 78 216; /* #1d4ed8 */
+
+    /* --- Secondary / supporting color --- */
+    --color-secondary: 100 116 139; /* #64748b */
+
+    /* --- Accent / highlight color --- */
+    --color-accent: 245 158 11; /* #f59e0b */
+
+    /* --- Surface backgrounds --- */
+    --color-surface: 255 255 255; /* #ffffff */
+    --color-surface-raised: 249 250 251; /* #f9fafb */
+
+    /* --- Text on colored backgrounds --- */
+    --color-on-primary: 255 255 255; /* #ffffff */
+    --color-on-secondary: 255 255 255; /* #ffffff */
+
+    /* --- Body text variants --- */
+    --color-muted: 107 114 128; /* #6b7280 */
+    --color-subtle: 229 231 235; /* #e5e7eb -- borders and dividers */
+
+    /* --- Semantic state colors --- */
+    --color-error: 220 38 38; /* #dc2626 */
+    --color-on-error: 255 255 255; /* #ffffff */
+    --color-error-strong: 185 28 28; /* #b91c1c, red-700 -- error TEXT on the bg-error/10 tint: 6.47:1 on white, 5.54:1 on the tint (the error red itself measured 4.13:1 there) */
+    --color-success: 21 128 61; /* #15803d, green-700: 5.02:1 on white, 4.57:1 on the success-subtle toast (axe flagged green-600 at 3.3:1) */
+    --color-on-success: 255 255 255; /* #ffffff */
+    --color-success-strong: 22 101 52; /* #166534, green-800 -- success TEXT on the bg-success/10 tint: 7.13:1 on white, 6.23:1 on the tint (green-700 measured 4.38:1 there) */
+    --color-warning: 217 119 6; /* #d97706 -- amber for validation / soft-fail: borders, icons, badges */
+    --color-warning-strong: 180 83 9; /* #b45309, amber-700 -- warning TEXT: 5.02:1 on white, 4.50:1 on the bg-warning/10 tint (amber-600 measured 2.86:1 on the "Only N left" pill, axe serious) */
+    --color-on-warning: 255 255 255; /* #ffffff */
+    --color-info: 37 99 235; /* #2563eb -- same as primary by default */
+    --color-on-info: 255 255 255; /* #ffffff */
+
+    /* --- Pricing tokens --- */
+    /* Color of the active "special" / final price on discounted items.
+       Defaults to the error red so the discount reads immediately; a
+       store can remap to `--color-primary` or a bespoke sale-hot-pink
+       without touching any .phtml. */
+    --color-price-sale: var(--color-error);
+
+    /* --- Extended tokens: secondary surface + text scale + helpers.
+       Each replaces an absolute palette class (banned in the theme) so every
+       color decision still resolves through a custom property. */
+    --color-surface-sunken: 248 250 252; /* #f8fafc -- slate-50, sub-page background blocks */
+    --color-surface-overlay: 241 245 249; /* #f1f5f9 -- modal/scrim backdrop */
+    --color-text-default: 17 24 39; /* #111827 -- primary body copy */
+    --color-text-secondary: 55 65 81; /* #374151 -- supporting copy */
+    --color-text-tertiary: 107 114 128; /* #6b7280 -- captions, muted helpers */
+    --color-border-default: 229 231 235; /* #e5e7eb */
+    --color-divider: 243 244 246; /* #f3f4f6 -- table row separators */
+    --color-error-hover: 220 38 38; /* #dc2626 -- destructive hover */
+    --color-error-active: 185 28 28; /* #b91c1c -- destructive pressed */
+    --color-success-subtle: 220 252 231; /* #dcfce7 -- success toast bg */
+    --color-warning-light: 253 224 71; /* #fde047 -- group-hover star icon */
+    --color-focus-ring: 99 102 241; /* #6366f1 -- focus ring */
+
+    /* --- Inverted surface (dark footer, cookie banner) --- */
+    /* An inverted surface is a dark band (typically the footer) with
+       light text and muted-light secondary text. A child theme can
+       redefine the pair without touching markup. */
+    --color-surface-inverted: 17 24 39; /* #111827 */
+    --color-on-inverted: 229 231 235; /* #e5e7eb */
+    --color-on-inverted-muted: 156 163 175; /* #9ca3af */
+    --color-subtle-inverted: 55 65 81; /* #374151 -- dividers inside dark surfaces */
+
+    /* --- Checkout aliases --- */
+    /* The checkout package reads --checkout-color-* tokens (its
+       Tailwind config in frontend/packages/module-checkout). Alias them
+       to the semantic tokens above so the checkout bundle inherits the store
+       look without a rebuild. Override in a child theme to give the
+       checkout a distinct visual identity from the rest of the store. */
+    --checkout-color-brand: var(--color-secondary);
+    --checkout-color-accent: var(--color-primary);
+    --checkout-color-danger: var(--color-error);
+    --checkout-color-muted: var(--color-muted);
+    --checkout-color-surface: var(--color-surface);
+    --checkout-color-surface-raised: var(--color-surface-raised);
+    --checkout-color-on-brand: var(--color-on-primary);
+    --checkout-color-on-accent: var(--color-on-primary);
+    --checkout-color-on-danger: var(--color-on-error);
+    --checkout-color-subtle: var(--color-subtle);
+}

package/src/tokens/index.css

@@ -0,0 +1,13 @@
+/* SPDX-License-Identifier: MIT */
+/* Copyright (c) 2026 Sergiu Ro -- magentofullstackdev */
+
+/*
+ * @magentofullstackdev/hyperion-shared -- design-token barrel.
+ *
+ * Imported by both @magentofullstackdev/hyperion-theme (via web/css/source/_theme.css)
+ * and @magentofullstackdev/hyperion-checkout (via src/styles/vars.css). All Hyperion
+ * Composer packages render against the same semantic palette.
+ */
+@import "./colors.css";
+@import "./typography.css";
+@import "./spacing.css";

package/src/tokens/spacing.css

@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: MIT */
+/* Copyright (c) 2026 Sergiu Ro -- magentofullstackdev */
+
+/*
+ * @magentofullstackdev/hyperion-shared -- spacing tokens.
+ *
+ * Section-level rhythm for theme chrome and content surfaces. Component-
+ * specific spacing (slider gap, swatch size, panel width, etc.) lives
+ * in the consuming package because it is component-specific, not part
+ * of the global design contract.
+ */
+:root {
+    --spacing-section: 2rem;
+}

package/src/tokens/typography.css

@@ -0,0 +1,20 @@
+/* SPDX-License-Identifier: MIT */
+/* Copyright (c) 2026 Sergiu Ro -- magentofullstackdev */
+
+/*
+ * @magentofullstackdev/hyperion-shared -- typography tokens.
+ *
+ * Single source of truth for type-scale and font stacks across the
+ * Hyperion suite. Override in a child theme's `_theme.css` to swap the
+ * font stack without touching markup.
+ */
+:root {
+    --font-family-base: ui-sans-serif, system-ui, sans-serif;
+    --font-size-base: 1rem;
+
+    /* --- Checkout font alias --- */
+    /* The checkout package reads --checkout-font-sans (its Tailwind
+       config in frontend/packages/module-checkout). Alias to the suite
+       font so the checkout inherits the store typography by default. */
+    --checkout-font-sans: var(--font-family-base);
+}