@luzmo/lucero 1.0.1-alpha.82 → 1.0.1-alpha.84

package/README.dist.md

@@ -0,0 +1,94 @@
+# Lucero
+
+**Luzmo's Design System** — A collection of reusable web components built with [Lit](https://lit.dev/) for creating consistent, accessible, and beautiful user interfaces.
+
+## Alpha
+
+> ⚠️ This package is in alpha state. Do not use in production. Expect breaking changes.
+
+## Installation
+
+```bash
+npm install @luzmo/lucero
+```
+
+## Usage
+
+Import individual components:
+
+```typescript
+import '@luzmo/lucero/button';
+import '@luzmo/lucero/text-field';
+import '@luzmo/lucero/menu';
+```
+
+Use in your HTML:
+
+```html
+<luzmo-button variant="primary">Click me</luzmo-button>
+<luzmo-text-field
+  label="Email"
+  placeholder="Enter your email"
+></luzmo-text-field>
+```
+
+## Available Components
+
+| Component            | Import                               |
+| -------------------- | ------------------------------------ |
+| Accordion            | `@luzmo/lucero/accordion`            |
+| Action Bar           | `@luzmo/lucero/action-bar`           |
+| Action Button        | `@luzmo/lucero/action-button`        |
+| Action Group         | `@luzmo/lucero/action-group`         |
+| Action Menu          | `@luzmo/lucero/action-menu`          |
+| Avatar               | `@luzmo/lucero/avatar`               |
+| Button               | `@luzmo/lucero/button`               |
+| Button Group         | `@luzmo/lucero/button-group`         |
+| Calendar             | `@luzmo/lucero/calendar`             |
+| Chat Message         | `@luzmo/lucero/chat-message`         |
+| Chat Message Group   | `@luzmo/lucero/chat-message-group`   |
+| Checkbox             | `@luzmo/lucero/checkbox`             |
+| Color Area           | `@luzmo/lucero/color-area`           |
+| Color Field          | `@luzmo/lucero/color-field`          |
+| Color Menu           | `@luzmo/lucero/color-menu`           |
+| Color Palette        | `@luzmo/lucero/color-palette`        |
+| Color Picker         | `@luzmo/lucero/color-picker`         |
+| Color Slider         | `@luzmo/lucero/color-slider`         |
+| Date Time Picker     | `@luzmo/lucero/date-time-picker`     |
+| Divider              | `@luzmo/lucero/divider`              |
+| Field Group          | `@luzmo/lucero/field-group`          |
+| Field Label          | `@luzmo/lucero/field-label`          |
+| Icon                 | `@luzmo/lucero/icon`                 |
+| Menu                 | `@luzmo/lucero/menu`                 |
+| Multi Language Field | `@luzmo/lucero/multi-language-field` |
+| Number Field         | `@luzmo/lucero/number-field`         |
+| Options              | `@luzmo/lucero/options`              |
+| Picker               | `@luzmo/lucero/picker`               |
+| Picker Button        | `@luzmo/lucero/picker-button`        |
+| Progress Circle      | `@luzmo/lucero/progress-circle`      |
+| Prompt Box           | `@luzmo/lucero/prompt-box`           |
+| Radio                | `@luzmo/lucero/radio`                |
+| Search               | `@luzmo/lucero/search`               |
+| Select               | `@luzmo/lucero/select`               |
+| Slider               | `@luzmo/lucero/slider`               |
+| Suggestion           | `@luzmo/lucero/suggestion`           |
+| Swatch               | `@luzmo/lucero/swatch`               |
+| Switch               | `@luzmo/lucero/switch`               |
+| Tabs                 | `@luzmo/lucero/tabs`                 |
+| Tags                 | `@luzmo/lucero/tags`                 |
+| Text Field           | `@luzmo/lucero/text-field`           |
+| Toast                | `@luzmo/lucero/toast`                |
+| Tooltip              | `@luzmo/lucero/tooltip`              |
+
+## Browser Support
+
+- Last 2 versions of Chrome
+- Last 2 versions of Firefox
+- Last 2 versions of Safari
+- Last 2 versions of Edge
+
+## License
+
+Copyright © 2025 Luzmo. All rights reserved.
+
+Lucero must be used according to the [Luzmo Terms of Service](https://www.luzmo.com/information-pages/terms-of-use). This license allows users with a current active Luzmo account to use Lucero.

package/README.md

@@ -2,9 +2,7 @@
 
 **Luzmo's Design System** — A collection of reusable web components built with [Lit](https://lit.dev/) for creating consistent, accessible, and beautiful user interfaces.
 
-## Alpha
-
-> ⚠️ This package is in alpha state. Do not use in production. Expect breaking changes.
+Lucero provides the foundational UI building blocks used across Luzmo products, ensuring visual consistency and reducing development time.
 
 ## Installation
 
@@ -12,83 +10,496 @@
 npm install @luzmo/lucero
 ```
 
-## Usage
-
-Import individual components:
-
-```typescript
+```ts
 import '@luzmo/lucero/button';
-import '@luzmo/lucero/text-field';
-import '@luzmo/lucero/menu';
 ```
 
-Use in your HTML:
-
 ```html
-<luzmo-button variant="primary">Click me</luzmo-button>
-<luzmo-text-field
-  label="Email"
-  placeholder="Enter your email"
-></luzmo-text-field>
+<luzmo-button>Click me</luzmo-button>
 ```
 
-## Available Components
-
-| Component            | Import                               |
-| -------------------- | ------------------------------------ |
-| Accordion            | `@luzmo/lucero/accordion`            |
-| Action Bar           | `@luzmo/lucero/action-bar`           |
-| Action Button        | `@luzmo/lucero/action-button`        |
-| Action Group         | `@luzmo/lucero/action-group`         |
-| Action Menu          | `@luzmo/lucero/action-menu`          |
-| Avatar               | `@luzmo/lucero/avatar`               |
-| Button               | `@luzmo/lucero/button`               |
-| Button Group         | `@luzmo/lucero/button-group`         |
-| Calendar             | `@luzmo/lucero/calendar`             |
-| Chat Message         | `@luzmo/lucero/chat-message`         |
-| Chat Message Group   | `@luzmo/lucero/chat-message-group`   |
-| Checkbox             | `@luzmo/lucero/checkbox`             |
-| Color Area           | `@luzmo/lucero/color-area`           |
-| Color Field          | `@luzmo/lucero/color-field`          |
-| Color Menu           | `@luzmo/lucero/color-menu`           |
-| Color Palette        | `@luzmo/lucero/color-palette`        |
-| Color Picker         | `@luzmo/lucero/color-picker`         |
-| Color Slider         | `@luzmo/lucero/color-slider`         |
-| Date Time Picker     | `@luzmo/lucero/date-time-picker`     |
-| Divider              | `@luzmo/lucero/divider`              |
-| Field Group          | `@luzmo/lucero/field-group`          |
-| Field Label          | `@luzmo/lucero/field-label`          |
-| Icon                 | `@luzmo/lucero/icon`                 |
-| Menu                 | `@luzmo/lucero/menu`                 |
-| Multi Language Field | `@luzmo/lucero/multi-language-field` |
-| Number Field         | `@luzmo/lucero/number-field`         |
-| Options              | `@luzmo/lucero/options`              |
-| Picker               | `@luzmo/lucero/picker`               |
-| Picker Button        | `@luzmo/lucero/picker-button`        |
-| Progress Circle      | `@luzmo/lucero/progress-circle`      |
-| Prompt Box           | `@luzmo/lucero/prompt-box`           |
-| Radio                | `@luzmo/lucero/radio`                |
-| Search               | `@luzmo/lucero/search`               |
-| Select               | `@luzmo/lucero/select`               |
-| Slider               | `@luzmo/lucero/slider`               |
-| Suggestion           | `@luzmo/lucero/suggestion`           |
-| Swatch               | `@luzmo/lucero/swatch`               |
-| Switch               | `@luzmo/lucero/switch`               |
-| Tabs                 | `@luzmo/lucero/tabs`                 |
-| Tags                 | `@luzmo/lucero/tags`                 |
-| Text Field           | `@luzmo/lucero/text-field`           |
-| Toast                | `@luzmo/lucero/toast`                |
-| Tooltip              | `@luzmo/lucero/tooltip`              |
-
-## Browser Support
+## Alpha
+
+This repository is in alpha state. Do not use the web components in production.
+Expect breaking changes.
+
+## Requirements
+
+Supported desktop browsers:
 
 - Last 2 versions of Chrome
 - Last 2 versions of Firefox
 - Last 2 versions of Safari
 - Last 2 versions of Edge
 
-## License
+## Design System
+
+### When to Create a Component
+
+Create a new component when:
+
+- **Reusability**: The UI pattern appears in 2+ places across the product
+- **Encapsulation**: The pattern has distinct behavior, state, or styling that should be isolated
+- **Composability**: It can be combined with other components to build complex UIs
+
+Do **not** create a component for:
+
+- One-off UI that won't be reused
+- Simple styling that can be achieved with CSS
+- Layout concerns (use CSS Grid/Flexbox instead)
+
+### Component Scope
+
+**Minimum scope** — A component should:
+
+- Do one thing well (single responsibility)
+- Be self-contained with its own styles and behavior
+- Work independently without requiring specific parent components
+
+**Maximum scope** — A design component should not:
+
+- Handle business logic or data fetching
+- Know about application-level routing or state
+- Exceed ~1000 lines of code (consider splitting)
+
+**Examples of good boundaries:**
+
+| ✅ Good      | ❌ Too broad           | ❌ Too narrow    |
+| ------------ | ---------------------- | ---------------- |
+| `button`     | `user-dashboard`       | `button-text`    |
+| `text-field` | `checkout-form`        | `input-border`   |
+| `menu`       | `navigation-with-auth` | `menu-item-icon` |
+
+## Naming Conventions
+
+### General Principles
+
+- **No abbreviations** — use full, descriptive words (`button` not `btn`, `configuration` not `cfg`)
+- **Consistency** — follow existing patterns in the codebase
+- **Clarity** — names should be self-documenting
+
+### Component Names
+
+- **Prefix**: All components use `luzmo-` prefix
+- **Format**: `luzmo-{component-name}` in kebab-case
+- **Class name**: PascalCase with `Luzmo` prefix (`LuzmoButton`, `LuzmoTextField`)
+
+```html
+<!-- ✅ Good -->
+<luzmo-button>
+  <luzmo-text-field>
+    <luzmo-action-menu>
+      <luzmo-date-time-picker>
+        <!-- ❌ Bad -->
+        <luzmo-btn>
+          <!-- Avoid abbreviations -->
+          <luzmo-textfield>
+            <!-- Use kebab-case for multi-word -->
+            <luzmo-ActionMenu>
+              <!-- No PascalCase in HTML --></luzmo-ActionMenu
+            ></luzmo-textfield
+          ></luzmo-btn
+        ></luzmo-date-time-picker
+      ></luzmo-action-menu
+    ></luzmo-text-field
+  ></luzmo-button
+>
+```
+
+### Attributes & Properties
+
+| Type            | HTML Attribute    | JS Property | Example                         |
+| --------------- | ----------------- | ----------- | ------------------------------- |
+| Boolean         | `kebab-case`      | `camelCase` | `read-only` → `readOnly`        |
+| String/enum     | `kebab-case`      | `camelCase` | `static-color` → `staticColor`  |
+| Complex objects | _(not reflected)_ | `camelCase` | `formatOptions`, `selectedItem` |
+
+**Rules:**
+
+1. **Boolean attributes** — presence means `true`, absence means `false`
+
+   ```html
+   <luzmo-button disabled>
+     <!-- disabled = true -->
+     <luzmo-button> <!-- disabled = false --></luzmo-button></luzmo-button
+   >
+   ```
+
+2. **Reflect to attribute** — primitive values should sync between property and attribute
+
+   ```javascript
+   el.size = 'large';
+   el.getAttribute('size'); // 'large'
+   ```
+
+3. **Kebab in HTML, camelCase in JS** — multi-word attributes
+
+   ```html
+   <luzmo-field
+     read-only
+     static-color="white"
+     pending-label="Loading..."
+   ></luzmo-field>
+   ```
+
+   ```javascript
+   el.readOnly = true;
+   el.staticColor = 'white';
+   el.pendingLabel = 'Loading...';
+   ```
+
+4. **Common boolean attributes** — use short, descriptive adjectives:
+
+   | ✅ Good    | ❌ Avoid     |
+   | ---------- | ------------ |
+   | `disabled` | `isDisabled` |
+   | `readonly` | `isReadOnly` |
+   | `open`     | `isOpen`     |
+   | `pending`  | `isPending`  |
+   | `invalid`  | `hasError`   |
+   | `quiet`    | `isQuiet`    |
+   | `focused`  | `isFocused`  |
+
+5. **Enum/variant attributes** — use lowercase values:
+
+   ```html
+   <luzmo-button variant="primary" size="m" treatment="fill">
+     <luzmo-picker placement="bottom-start"></luzmo-picker
+   ></luzmo-button>
+   ```
+
+### Methods
+
+| Type           | Format       | Example                                     |
+| -------------- | ------------ | ------------------------------------------- |
+| Public         | `camelCase`  | `focus()`, `click()`, `toggle()`, `close()` |
+| Event handlers | `handle*`    | `handleChange()`, `handleKeydown()`         |
+| Internal       | `_camelCase` | `_updateValue()`, `_cachedItems`            |
+
+**Rules:**
+
+1. **Action methods** — use imperative verbs
+
+   ```typescript
+   toggle(open?: boolean): void    // Toggle state
+   close(): void                   // Close the component
+   focus(options?: FocusOptions): void
+   select(): void                  // Select all text
+   checkValidity(): boolean        // Validate and return result
+   ```
+
+2. **Getters/setters** — use noun-based names
+
+   ```typescript
+   get focusElement(): HTMLElement
+   get selectedItem(): LuzmoMenuItem | undefined
+   set value(val: string)
+   ```
+
+3. **Internal methods** — use `@internal` JSDoc or underscore prefix
+
+   ```typescript
+   /** @internal */
+   protected _updateCache(): void
+   private _handleSlotchange(): void
+   ```
+
+### Events
+
+| Type             | Format                 | Example                            |
+| ---------------- | ---------------------- | ---------------------------------- |
+| Standard HTML    | lowercase              | `change`, `input`, `focus`, `blur` |
+| Custom component | `luzmo-` + kebab-case  | `luzmo-opened`, `luzmo-closed`     |
+| Internal         | `luzmo-` + descriptive | `luzmo-menu-item-added-or-updated` |
+
+**Rules:**
+
+1. **Prefer standard events** — when behavior matches HTML semantics
+
+   ```typescript
+   // Use standard 'change' for value changes
+   this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+   ```
+
+2. **Custom events** — use `luzmo-` prefix with descriptive names
+
+   ```typescript
+   // Component lifecycle events
+   this.dispatchEvent(
+     new Event('luzmo-opened', { bubbles: true, composed: true })
+   );
+   this.dispatchEvent(
+     new Event('luzmo-closed', { bubbles: true, composed: true })
+   );
+
+   // With detail data
+   this.dispatchEvent(
+     new CustomEvent('luzmo-change', {
+       detail: { value, oldValue },
+       bubbles: true,
+       composed: true
+     })
+   );
+   ```
+
+3. **Event naming pattern**:
+
+   | Pattern                 | Use case                  |
+   | ----------------------- | ------------------------- |
+   | `luzmo-{verb}-ed`       | After action completed    |
+   | `luzmo-{noun}-{action}` | Specific component events |
+
+### CSS Custom Properties
+
+| Type               | Format                       | Example                               |
+| ------------------ | ---------------------------- | ------------------------------------- |
+| Design tokens      | `--luzmo-{category}-{name}`  | `--luzmo-primary`, `--luzmo-shadow-m` |
+| Component-specific | `--luzmo-{component}-{prop}` | `--luzmo-button-height`               |
+
+**Examples:**
+
+```css
+/* Color tokens */
+--luzmo-primary
+--luzmo-background-color
+--luzmo-font-color
+--luzmo-border-color
+
+/* Sizing/spacing */
+--luzmo-shadow-s
+--luzmo-shadow-m
+--luzmo-shadow-l
+```
+
+### Slots
+
+| Format  | Example                                         |
+| ------- | ----------------------------------------------- |
+| Default | `<slot></slot>` — main content                  |
+| Named   | `<slot name="icon">`, `<slot name="help-text">` |
+
+**Common slot names:**
+
+- `icon` — icon slot
+- `label` — label content
+- `help-text` — helper text below field
+- `negative-help-text` — error message
+- `description` — descriptive text
+- `tooltip` — tooltip content
+
+### File Names
+
+| Type         | Format                        | Example                  |
+| ------------ | ----------------------------- | ------------------------ |
+| Component    | `{component}.ts`              | `button.ts`              |
+| Styles       | `{component}.module.scss`     | `button.module.scss`     |
+| Stories      | `{component}.stories.ts`      | `button.stories.ts`      |
+| Unit tests   | `{component}.test.ts`         | `button.test.ts`         |
+| Visual tests | `{component}-visual.test.ts`  | `button-visual.test.ts`  |
+| Memory tests | `{component}-memory.test.ts`  | `button-memory.test.ts`  |
+| Interactions | `{component}.interactions.ts` | `button.interactions.ts` |
+
+### TypeScript Types & Interfaces
+
+| Type       | Format     | Example                              |
+| ---------- | ---------- | ------------------------------------ |
+| Types      | PascalCase | `ButtonVariants`, `Placement`        |
+| Interfaces | PascalCase | `MenuChildItem`, `OpenableElement`   |
+| Enums      | PascalCase | `OverlayState`, `TriggerInteraction` |
+
+### Common Naming Patterns Summary
+
+| Category   | Pattern                     | ✅ Good           | ❌ Avoid              |
+| ---------- | --------------------------- | ----------------- | --------------------- |
+| Components | `luzmo-{name}`              | `luzmo-button`    | `luzmo-btn`           |
+| Properties | camelCase                   | `pendingLabel`    | `pending_label`       |
+| Attributes | kebab-case                  | `pending-label`   | `pendingLabel`        |
+| Methods    | camelCase verb              | `handleChange()`  | `change_handler()`    |
+| Events     | `luzmo-` prefix             | `luzmo-opened`    | `onOpen`, `openEvent` |
+| CSS vars   | `--luzmo-{name}`            | `--luzmo-primary` | `--primary`           |
+| Internal   | `_camelCase` or `@internal` | `_cachedItems`    | `cachedItems__`       |
+
+## CSS Reset Protection
+
+Lucero components are used in host apps that include CSS resets (Tailwind, Normalize, etc.). Tailwind's preflight injects `* { border-width: 0; border-style: solid; border-color: #e5e7eb; }`, which — per the CSS cascade spec — overrides normal `:host` styles in Shadow DOM because outer-context author styles take precedence.
+
+**Rule**: All `border-width`, `border-style`, `border-color`, and `border` shorthand declarations on any `:host(...)` selector (including state variants and pseudo-elements) **must** use `!important`.
+
+```scss
+:host {
+  // a lot of reset css from libraries like tailwind, so we set !important
+  border-width: var(--luzmo-tag-border-width, var(--tag-border-width)) !important;
+  border-style: solid !important;
+  border-color: var(
+    --highcontrast-tag-border-color,
+    var(--luzmo-tag-border-color, var(--tag-border-color))
+  ) !important;
+}
+```
+
+This is safe because `!important` in the inner tree always beats `!important` in the outer tree, and consumer customization via CSS custom properties is unaffected. See `rules/styles.md` for the full rationale and what does/doesn't need protection.
+
+## Testing
+
+### Commands
+
+| Command                      | Description                             |
+| ---------------------------- | --------------------------------------- |
+| `npm run test`               | Run unit + visual tests in all browsers |
+| `npm run test:chromium`      | Run unit + visual tests in Chromium     |
+| `npm run test:firefox`       | Run unit tests in Firefox               |
+| `npm run test:webkit`        | Run unit tests in WebKit                |
+| `npm run test:visual`        | Run visual regression tests only        |
+| `npm run test:visual:update` | Update visual regression screenshots    |
+| `npm run test:memory`        | Run memory leak tests                   |
+| `npm run test:storybook`     | Run Storybook interaction tests         |
+| `npm run test:all`           | Run all tests                           |
+
+### Test File Structure
+
+```
+src/components/{component}/
+├── {component}.ts              # Component implementation
+├── {component}.module.scss     # Component styles
+├── tests/
+│   ├── *.test.ts               # Unit + behavioral a11y tests
+│   ├── *-a11y.test.ts          # Static axe-core a11y scan
+│   ├── *-visual.test.ts        # Visual regression tests
+│   ├── *-memory.test.ts        # Memory leak tests
+│   ├── *.interactions.ts       # Storybook interaction tests
+│   └── __screenshots__/        # Visual test reference images
+└── stories/
+    └── *.stories.ts            # Storybook stories
+```
+
+See [File Names](#file-names) for naming conventions.
+
+### Test Types
+
+#### Unit Tests (`*.test.ts`)
+
+Standard Vitest tests for component behavior, accessibility, and API validation.
+
+```typescript
+import { fixture, expect } from '@open-wc/testing';
+import { html } from 'lit';
+
+describe('Component', () => {
+  it('should render', async () => {
+    const el = await fixture(html`<luzmo-component></luzmo-component>`);
+    expect(el).to.exist;
+  });
+});
+```
+
+#### Visual Regression Tests (`*-visual.test.ts`)
+
+Screenshot-based tests using Storybook stories. Run only in Chromium.
+
+```typescript
+import { composeStories } from 'storybook/preview-api';
+import * as stories from '../stories/{component}.stories';
+
+const composedStories = composeStories(stories);
+
+it('Default - renders correctly', async () => {
+  const el = await renderStory(composedStories.Default);
+  await expect(el).toMatchScreenshot('{component}-default');
+});
+```
+
+#### Memory Tests (`*-memory.test.ts`)
+
+Tests for memory leaks when components mount/unmount repeatedly.
+
+```typescript
+import { testForMemoryLeaks } from '../../../test-utils/testing-helpers.js';
+import { componentMarkup } from '../stories/template.js';
+
+testForMemoryLeaks(componentMarkup({}));
+```
+
+#### Interaction Tests (`*.interactions.ts`)
+
+Storybook play functions for testing user interactions. Used in stories with `play` property.
+
+```typescript
+import { expect, userEvent } from 'storybook/test';
+
+export const testDefault = async ({ canvasElement }) => {
+  const el = canvasElement.querySelector('luzmo-component');
+  await expect(el).toBeInTheDocument();
+  await userEvent.click(el);
+};
+```
+
+#### Accessibility Tests
+
+Every component must include two types of accessibility tests:
+
+##### Static A11y Tests (`*-a11y.test.ts`)
+
+Axe-core scans that check for WCAG 2.x violations on the component's default rendering. Create a separate `*-a11y.test.ts` file for each component:
+
+```typescript
+import { afterEach, describe, expect, it } from 'vitest';
+import { a11yFixture, html, runAxe } from '../../../test-utils/a11y-test-helpers';
+import '../';
+
+afterEach(() => { document.body.innerHTML = ''; });
+
+describe('luzmo-component - accessibility', () => {
+  it('has no axe violations', async () => {
+    const { el } = await a11yFixture(html`
+      <luzmo-component label="Example"></luzmo-component>
+    `);
+    const results = await runAxe(el);
+    expect(results.violations).toEqual([]);
+  });
+});
+```
+
+##### Behavioral A11y Tests (in `*.test.ts`)
+
+Keyboard navigation, focus management, and ARIA state transition tests. Added as a `describe('keyboard navigation', ...)` block in the main test file. Expected coverage depends on the component's ARIA role:
+
+| ARIA pattern | Expected keyboard tests |
+|---|---|
+| Composite widget (menu, listbox, radio group, toolbar, tablist) | Arrow key navigation, Home/End, skip disabled, wrap-around |
+| Expandable (accordion, disclosure, combobox, picker) | Enter/Space to toggle, Escape to close, focus management on open/close |
+| Value (slider, number-field, color-area) | Arrow keys to adjust value, Home/End for min/max, step modifiers |
+| Overlay (dialog, popover) | Escape to dismiss, focus trap (modal), focus return to trigger |
+| Form submit (prompt-box, search) | Enter to submit |
+
+Example (roving tabindex navigation):
+
+```typescript
+it('moves focus with ArrowDown', async () => {
+  const el = await fixture(html`
+    <luzmo-component>
+      <luzmo-item class="first">A</luzmo-item>
+      <luzmo-item class="second">B</luzmo-item>
+    </luzmo-component>
+  `);
+  const first = el.querySelector('.first');
+  const second = el.querySelector('.second');
+  await elementUpdated(el);
+
+  first.focus();
+  await elementUpdated(el);
+
+  el.dispatchEvent(arrowDownEvent());
+  await nextFrame();
+
+  expect(document.activeElement).to.equal(second);
+});
+```
 
-Copyright © 2025 Luzmo. All rights reserved.
+### Expectations
 
-Lucero must be used according to the [Luzmo Terms of Service](https://www.luzmo.com/information-pages/terms-of-use). This license allows users with a current active Luzmo account to use Lucero.
+- **All components** should have unit tests covering core functionality
+- **All components** must have a static axe a11y test (`*-a11y.test.ts`)
+- **Interactive components** must have behavioral keyboard navigation tests in their main `*.test.ts`
+- **Visual tests** should cover key visual states (default, disabled, sizes, variants)
+- **Memory tests** ensure components don't leak memory on mount/unmount cycles
+- **Interaction tests** validate user flows in Storybook

package/dist/LICENSE

@@ -0,0 +1,16 @@
+Lucero - The design system for Luzmo.
+
+Copyright © 2025 Luzmo
+All rights reserved.
+Lucero (“Luzmo Design System”) must be used according to the Luzmo Terms of Service.
+This license allows users with a current active Luzmo account to use Lucero.
+This license terminates automatically if a user no longer has an active Luzmo account.
+Please view the Luzmo Terms of Service at: https://www.luzmo.com/information-pages/terms-of-use.
+
+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.