@umbra.ui/core 0.4.6 → 0.5.0

package/src/components/pickers/IconPicker/README.md

@@ -64,6 +64,48 @@ const handleIconChange = (icon: IconKey) => {
 </style>
 ```
 
+## Custom Label Slot
+
+When you provide a custom `label` slot, the default trigger icon/chevron visuals
+are removed so you can fully control the trigger UI and animation.
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+
+const selectedIcon = ref<IconKey>("home");
+const triggerText = computed(() => `Icon: ${selectedIcon.value}`);
+</script>
+
+<template>
+  <IconPicker v-model:icon="selectedIcon">
+    <template #label>
+      <span class="icon-chip">{{ triggerText }}</span>
+    </template>
+  </IconPicker>
+</template>
+
+<style module>
+.icon-chip {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.353rem 0.529rem;
+  border-radius: 0.471rem;
+  background: var(--background-subtle, #f3f4f6);
+  color: var(--text-primary, #111827);
+  border: 1px solid var(--border-soft, #d1d5db);
+}
+</style>
+```
+
+### Hiding the Label
+
+```vue
+<IconPicker v-model:icon="selectedIcon" :label="false" />
+```
+
 ## Props
 
 | Prop Name       | Type        | Required | Default     | Description                               |
@@ -71,6 +113,7 @@ const handleIconChange = (icon: IconKey) => {
 | `icon`          | `string`    | Yes      | `""`        | Currently selected icon key               |
 | `pickerOffsetX` | `number`    | No       | `0`         | Horizontal offset for picker positioning  |
 | `preventPopup`  | `boolean`   | No       | `false`     | Whether to prevent the popup from opening |
+| `label`         | `boolean`   | No       | `true`      | Show or hide the trigger label/slot       |
 | `iconList`      | `IconKey[]` | No       | `undefined` | Custom list of available icons            |
 | `iconSize`      | `number`    | No       | `18`        | Size of the displayed icon                |
 

package/src/skills/README.md

@@ -0,0 +1,108 @@
+# Umbra Component Skills Index
+
+This directory contains AI-agent skill guides for Umbra input and control components.
+
+## Quick Usage Pattern
+1. Pick the skill matching the input family.
+2. Read `SKILL.md` for implementation flow and developer questions.
+3. Read `reference.md` when available for props/events/pitfalls.
+
+## Input Skills
+- `umbra.ui-input-text`
+  - `SKILL.md`
+- `umbra.ui-input-phone`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-input-number`
+  - `SKILL.md`
+- `umbra.ui-input-email`
+  - `SKILL.md`
+- `umbra.ui-input-card`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-input-secure`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-input-crypto-address`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-input-otp`
+  - `SKILL.md`
+- `umbra.ui-input-tags`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-input-string-capture`
+  - `SKILL.md`
+- `umbra.ui-input-search`
+  - `SKILL.md`
+  - `reference.md`
+
+## Control Skills
+- `umbra.ui-control-button`
+  - `SKILL.md`
+- `umbra.ui-control-checkbox`
+  - `SKILL.md`
+- `umbra.ui-control-dropdown`
+  - `SKILL.md`
+- `umbra.ui-control-icon-button`
+  - `SKILL.md`
+- `umbra.ui-control-inline-dropdown`
+  - `SKILL.md`
+- `umbra.ui-control-radio`
+  - `SKILL.md`
+- `umbra.ui-control-range-slider`
+  - `SKILL.md`
+- `umbra.ui-control-segmented-control`
+  - `SKILL.md`
+- `umbra.ui-control-slider`
+  - `SKILL.md`
+- `umbra.ui-control-stepper`
+  - `SKILL.md`
+- `umbra.ui-control-switch`
+  - `SKILL.md`
+
+## Model Skills
+- `umbra.ui-model-popover`
+  - `SKILL.md`
+- `umbra.ui-model-sheet`
+  - `SKILL.md`
+- `umbra.ui-model-sidebar`
+  - `SKILL.md`
+
+## Menu Skills
+- `umbra.ui-menu-action-menu`
+  - `SKILL.md`
+
+## Dialog Skills
+- `umbra.ui-dialog-alert`
+  - `SKILL.md`
+- `umbra.ui-dialog-toast`
+  - `SKILL.md`
+
+## Indicator Skills
+- `umbra.ui-indicator-progress-bar`
+  - `SKILL.md`
+- `umbra.ui-indicator-tooltip`
+  - `SKILL.md`
+
+## Picker Skills
+- `umbra.ui-picker-date`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-picker-collection`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-picker-color`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-picker-icon`
+  - `SKILL.md`
+  - `reference.md`
+- `umbra.ui-picker-file`
+  - `SKILL.md`
+  - `reference.md`
+
+## Authoring Notes
+- Keep skill names flat and stable (`umbra.ui-input-*`, `umbra.ui-control-*`, `umbra.ui-model-*`, `umbra.ui-menu-*`, `umbra.ui-dialog-*`, `umbra.ui-indicator-*`, `umbra.ui-picker-*`).
+- Prefer concrete implementation checklists over generic guidance.
+- Add `reference.md` for families with multiple components or complex contracts.

package/src/skills/umbra.ui-colors-application/SKILL.md

@@ -0,0 +1,102 @@
+# Umbra Skill: Apply Color System To Components
+
+Use this skill when converting a Vue component's colors to the Umbra color system from `@umbra.ui/colors`.
+
+## When To Use
+
+- A component uses hardcoded colors (`#hex`, `rgb`, `hsl`) and needs tokenization.
+- A component needs light/dark theme parity.
+- A component needs semantic color roles (text, border, surface, status, accent).
+- A component must align with `packages/colors/README.md` scale and pairing guidance.
+
+## Required Context Checklist
+
+- Target component file path(s) and scope (single file vs full feature area).
+- Whether to use semantic CSS tokens (`--text-1`, `--border-2`, etc.) or raw scale tokens.
+- Theme requirement: light only, dark only, or both.
+- Brand/accent palette selection.
+- **Gray palette selection** (`gray`, `mauve`, `slate`, `sage`, `olive`, `sand`).
+- Required interaction states (default, hover, active, selected, disabled, focus, error).
+- Contrast constraints (WCAG/APCA expectations, design QA requirements).
+- Any do-not-change visual constraints from design/product.
+
+## Ask Developer If Missing
+
+- "Which gray palette do you want for this component (`gray`, `mauve`, `slate`, `sage`, `olive`, or `sand`)?"
+- "Should this component use semantic tokens first (`--text-1`, `--background-1`, etc.), or explicit family tokens (like `--blue-9`)?"
+- "What accent family should represent primary actions in this component?"
+- "Do we need both light and dark theming now, or only one mode?"
+- "Which status families should we use for `error`, `success`, `warning`, and `info`?"
+- "Are there any visual elements that must keep exact legacy color values?"
+- "What are the required states to style (hover, active, focus, disabled, selected, invalid)?"
+- "Do you want this conversion to include nearby child elements for consistency, or keep it strictly scoped?"
+
+## Conversion Workflow
+
+1. Inventory all current color usages in template/style/script (including inline styles and computed class/style bindings).
+2. Classify each usage into a role:
+   - surface/background
+   - control/background-interactive
+   - border/separator/focus ring
+   - text/icon
+   - semantic status (error/success/warning/info)
+3. Replace raw values with token references:
+   - Prefer semantic aliases for reusable UI meaning.
+   - Use raw family scale steps for brand accents and highly specific visual treatments.
+4. Map states to nearby scale steps consistently:
+   - surface: `1-5`
+   - borders: `6-8`
+   - solids/fills: `9-10`
+   - text/icon: `11-12`
+5. Ensure light/dark token parity with the same role mapping in both themes.
+6. Validate contrast and state clarity (especially disabled, focus, and invalid).
+7. Keep naming readable and role-driven (`textPrimary`, `surfaceInteractiveHover`, etc.).
+
+## Practical Mapping Guidance
+
+- Text:
+  - Primary text -> `--text-1` (or `family12`)
+  - Secondary text -> `--text-2` (or `family11`)
+- Surfaces:
+  - App/card baseline -> `--background-1`
+  - Subtle nested areas -> `--background-2`
+  - Interactive hover/active -> family `4/5` or control aliases
+- Borders:
+  - Subtle separators -> `--border-3` or family `6`
+  - Interactive border -> `--border-2` / family `7`
+  - Focus ring -> family `8` (or accent `8`)
+- Solids:
+  - Primary fills -> family `9`
+  - Hovered primary fills -> family `10`
+- Semantic states:
+  - Error -> `--error` or chosen error family
+  - Success -> `--success` or chosen success family
+  - Warning -> `--warning` or chosen warning family
+  - Info -> `--info` or chosen info family
+
+## Rules Of Thumb
+
+- Do not preserve ad-hoc one-off colors unless explicitly requested.
+- Prefer role consistency over visual matching every old hex exactly.
+- Avoid mixing many saturated families in one component without intent.
+- If the component is mostly utility UI, neutral tokens should dominate.
+- If a solid fill uses step `9/10`, verify foreground text color choice is readable.
+
+## Validation And Edge Cases
+
+- Hover/active/focus/disabled are all visibly distinct.
+- Invalid and success states remain obvious in both themes.
+- Token usage is consistent between CSS modules, scoped styles, and inline style bindings.
+- No leftover hardcoded color literals remain unless documented as intentional.
+- Existing component behavior is unchanged (color migration only).
+
+## Definition Of Done
+
+- All target color values are tokenized with Umbra color principles.
+- Gray palette and accent/status decisions are confirmed with the developer.
+- Theme behavior (light/dark as required) is complete and consistent.
+- Semantic/role mapping is explicit and maintainable for future edits.
+
+## Additional Resources
+
+- For a component-by-component token matrix and ready-made recipes, see [reference.md](reference.md).

package/src/skills/umbra.ui-colors-application/reference.md

@@ -0,0 +1,178 @@
+# Umbra Colors Application Reference
+
+Use this document with `SKILL.md` to make color conversion decisions quickly and consistently.
+
+## Decision Matrix
+
+Use this as the default mapping unless the developer requests a specific deviation.
+
+| UI role | Preferred semantic token | Raw fallback pattern |
+| --- | --- | --- |
+| App/page background | `--background-1` | `neutral1` or `neutral2` |
+| Nested/subtle surface | `--background-2` | `neutral2` or family `2` |
+| Default interactive surface | `--control-3` | family `3` |
+| Hover interactive surface | `--control-2` | family `4` |
+| Active/selected interactive surface | `--control-1` | family `5` |
+| Subtle border/separator | `--border-3` | family `6` |
+| Control border | `--border-2` | family `7` |
+| Focus ring / strong border | `--border-1` | family `8` or accent `8` |
+| High emphasis solid | n/a | family `9` |
+| High emphasis solid hover | n/a | family `10` |
+| Primary text | `--text-1` | neutral `12` |
+| Secondary text | `--text-2` | neutral `11` |
+| Tertiary text/meta | `--text-3` | neutral `10` |
+| Link text | `--link` | info family `11` |
+| Error state | `--error` | error family `9-11` |
+| Success state | `--success` | success family `9-11` |
+| Warning state | `--warning` | warning family `9-11` |
+| Info state | `--info` | info family `9-11` |
+
+## Component Recipes
+
+## Input (text-like controls)
+
+Recommended baseline:
+
+- Container background: `--background-1` (or neutral `1/2`)
+- Border: `--border-2`
+- Text: `--text-1`
+- Placeholder/meta: `--text-3`
+- Hover border: `--border-1` or neutral `8`
+- Focus ring: accent `8` (or semantic focus token if project defines one)
+- Invalid:
+  - border/ring: `--error` or error family `8/9`
+  - helper text: error family `11`
+- Disabled:
+  - surface shift toward `--background-2`
+  - text shift to `--text-3`
+
+## Button
+
+### Primary button
+- Background: accent `9`
+- Hover: accent `10`
+- Text: choose readable foreground (often white for most accent families)
+- Focus ring: accent `8` or alpha accent ring token
+- Disabled:
+  - background toward neutral `4/5`
+  - text toward neutral `10/11`
+
+### Secondary/ghost button
+- Background rest: transparent or family `3`
+- Hover: family `4`
+- Active: family `5`
+- Border: family `7`
+- Text/icon: family `11/12` or semantic text tokens
+
+## Alert / callout
+
+For each intent (`error`, `success`, `warning`, `info`):
+
+- Background tint: family `3` (or `2` for subtler variant)
+- Border: family `6/7`
+- Title text/icon: family `11/12`
+- Body text: `--text-1` or family `11`
+
+Keep intent colors mostly on icon/title/border; avoid overwhelming full-body saturation.
+
+## Table row / list item
+
+- Base row: transparent or `--background-1`
+- Zebra stripe (optional): `--background-2`
+- Hover row: family `3` or `--control-3`
+- Selected row: family `4/5` (same family as related accent if selection is semantic)
+- Row divider: `--border-3`
+- Primary text: `--text-1`
+- Secondary text: `--text-2`
+
+## Selected state (generic pattern)
+
+For chips, menu items, segmented items, tabs:
+
+- Rest selected bg: family `5`
+- Hover selected bg: family `6` or stronger nearby tone
+- Selected border: family `7/8`
+- Selected label/icon: family `11/12`
+
+Use one family consistently for selected-state visuals inside one control.
+
+## Theme And Palette Guidance
+
+## Conversion Prompt Template
+
+Use this exact message when project context is missing before converting a component:
+
+```md
+Before I convert colors in `[component-path]`, please confirm:
+
+1) Gray palette:
+- Which neutral family should I use: `gray`, `mauve`, `slate`, `sage`, `olive`, or `sand`?
+
+2) Accent and semantic families:
+- Primary accent family:
+- Error family:
+- Success family:
+- Warning family:
+- Info family:
+
+3) Token strategy:
+- Prefer semantic tokens first (`--text-1`, `--background-1`, etc.), or allow direct family tokens (`--blue-9`, etc.) where useful?
+
+4) Theme scope:
+- Light only, dark only, or both?
+
+5) Required states:
+- Which states must be implemented: hover, active, focus, disabled, selected, invalid?
+
+6) Constraints:
+- Any colors/elements that must remain visually unchanged?
+- Should I keep conversion strictly to this file, or include adjacent child elements for consistency?
+```
+
+If the developer does not specify:
+
+- Use `gray` for neutral family.
+- Use semantic tokens for shared UI roles.
+- Implement both light and dark where supported.
+- Include at least: hover, focus, disabled, and invalid states for interactive controls.
+
+## Gray palette selection
+
+Ask developer first if not provided:
+
+- `gray`: pure neutral, minimal hue bias
+- `mauve`: purple-cool neutral
+- `slate`: blue-cool neutral
+- `sage`: green neutral
+- `olive`: yellow-green neutral
+- `sand`: warm neutral
+
+Safe default when unsure: `gray`.
+
+## Accent text-on-solid guidance
+
+For step `9/10` solids:
+
+- Usually light text works for most saturated families.
+- `sky`, `mint`, `lime`, `yellow`, and `amber` often need dark foreground text.
+
+Always verify readability in both light and dark themes.
+
+## State Contrast Checklist
+
+Before finalizing color conversion, verify:
+
+- Default vs hover is visible.
+- Hover vs active is visible.
+- Focus ring is visible over nearby surfaces.
+- Disabled is clearly non-interactive but still readable.
+- Invalid and success are distinct from normal state.
+- Selected and focused are distinguishable when both can occur.
+
+## Anti-Patterns
+
+- Keeping arbitrary legacy hex values "just because they look close."
+- Mixing multiple accent families in one small control without semantic reason.
+- Using high-saturation step `9` for large backgrounds where subtle surfaces are expected.
+- Using `11/12` text values from unrelated families when semantic text tokens are available.
+- Styling only light mode and leaving dark mode inconsistent.

package/src/skills/umbra.ui-control-button/SKILL.md

@@ -0,0 +1,34 @@
+# Umbra Skill: Button
+
+Use this skill for action buttons built with Umbra `Button`.
+
+## When To Use
+- Primary/secondary user actions (submit, continue, cancel, delete).
+- Calls to backend actions where disabled/active state matters.
+- Buttons that need consistent visual variants across the app.
+
+## Required Context Checklist
+- Action intent and click handler.
+- Visual variant: `buttonType`, `buttonStyle`, `buttonSize`.
+- Interaction state: `normal`, `active`, or `disabled`.
+- Title text and optional tooltip.
+
+## Ask Developer If Missing
+- "What action does this button trigger?"
+- "Which variant should this use (type/style/size)?"
+- "When should it be disabled or show active state?"
+
+## Implementation Recipe
+1. Import `Button` from `@umbra-ui/core`.
+2. Render with `title`, variant props, and state.
+3. Wire `@click` to domain action.
+4. If state is controlled externally, also handle `@update:state`.
+
+## Validation And Edge Cases
+- Disabled state must block unintended actions.
+- Destructive actions should use warning/danger style.
+- Ensure tooltip copy is clear for icon-like or ambiguous labels.
+
+## Definition Of Done
+- Variant and state match UI requirements.
+- Click behavior and disabled rules work correctly.

package/src/skills/umbra.ui-control-checkbox/SKILL.md

@@ -0,0 +1,34 @@
+# Umbra Skill: Checkbox
+
+Use this skill for boolean or multi-select toggle inputs with Umbra `Checkbox`.
+
+## When To Use
+- Single true/false settings.
+- Checklist UIs where multiple selections are allowed.
+- Compact selection controls in forms and list rows.
+
+## Required Context Checklist
+- Checked source of truth (`isChecked` binding).
+- Visual mode: `checkboxType` (`circle`, `square`, `plain`).
+- Size requirements and accessibility label context.
+- Update pathway from UI to model/store.
+
+## Ask Developer If Missing
+- "Is this single boolean or part of a checklist?"
+- "Which checkbox style should be used?"
+- "What model field should receive `update:isChecked`?"
+
+## Implementation Recipe
+1. Import `Checkbox`.
+2. Bind checked state via `:is-checked`.
+3. Handle `@update:is-checked` to persist change.
+4. Pair with visible label text nearby for clarity.
+
+## Validation And Edge Cases
+- Ensure event names use correct casing in Vue templates.
+- Checkbox interaction should remain stable in dynamic lists.
+- Verify size and hit target are usable on touch devices.
+
+## Definition Of Done
+- Checked state is fully controlled by parent state.
+- Style/size match design and state updates persist.

package/src/skills/umbra.ui-control-dropdown/SKILL.md

@@ -0,0 +1,34 @@
+# Umbra Skill: Dropdown
+
+Use this skill for single-selection lists using Umbra `Dropdown`.
+
+## When To Use
+- Selection from predefined options with optional subtitles.
+- Forms where selected item is an object (`DropdownItem`).
+- Flows requiring keyboard-accessible select behavior.
+
+## Required Context Checklist
+- `items: DropdownItem[]` source and option IDs.
+- Selected value shape (`DropdownItem | null`) and persistence.
+- Placeholder copy and disabled-item policy.
+- Overlay behavior (`showOverlay`) for page context.
+
+## Ask Developer If Missing
+- "What is the exact option list and selected value type?"
+- "Should any options be disabled?"
+- "Do we need outside overlay while open?"
+
+## Implementation Recipe
+1. Import `Dropdown` and `DropdownItem`.
+2. Define `items` and `selectedItem`.
+3. Render with `v-model` and `placeholder`.
+4. Handle `@change` for side effects.
+
+## Validation And Edge Cases
+- Use stable IDs for option identity.
+- Handle `null` selection where field is optional.
+- Verify keyboard flow: open, navigate, select, escape.
+
+## Definition Of Done
+- Dropdown selection updates model correctly.
+- Disabled/placeholder behavior and keyboard UX work as expected.

package/src/skills/umbra.ui-control-icon-button/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: IconButton
+
+Use this skill for icon-only actions with Umbra `IconButton`.
+
+## When To Use
+- Toolbar actions, compact controls, and action menus.
+- Repeated actions where iconography is recognizable.
+- UI requiring small footprint with optional tooltip.
+
+## Required Context Checklist
+- Icon key (`iconName`) and semantic meaning.
+- Visual variant: `buttonType`, `buttonStyle`, size.
+- State rules (`normal`, `active`, `disabled`).
+- Tooltip content for accessibility/clarity.
+
+## Ask Developer If Missing
+- "Which icon should represent this action?"
+- "Should the button show active/pressed state?"
+- "Is tooltip text required for discoverability?"
+
+## Implementation Recipe
+1. Import `IconButton`.
+2. Set `icon-name` and desired variant props.
+3. Wire `@click` to action and optional `@update:state`.
+4. Add `tooltip` for ambiguous icons.
+
+## Validation And Edge Cases
+- Confirm icon exists in `@umbra-ui/icons`.
+- Disabled state must block action dispatch.
+- Ensure icon-only controls still have contextual label nearby or tooltip.
+
+## Definition Of Done
+- Icon button renders correct icon/variant and triggers expected action.

package/src/skills/umbra.ui-control-inline-dropdown/SKILL.md

@@ -0,0 +1,32 @@
+# Umbra Skill: InlineDropdown
+
+Use this skill for compact inline selection with Umbra `InlineDropdown`.
+
+## When To Use
+- Space-constrained selectors embedded in rows/cards.
+- Lightweight option switching without full popover complexity.
+- Inline editing surfaces where value changes are frequent.
+
+## Required Context Checklist
+- `items` list shape (`{ id, title }[]`).
+- Bound selected item (`modelValue`) and nullable behavior.
+- Placeholder copy for empty selection.
+- Side-effect handling on item selection.
+
+## Ask Developer If Missing
+- "What item list should this component display?"
+- "Can selection be empty, or must one item always be selected?"
+- "Should we react to `itemSelected` for analytics/workflow?"
+
+## Implementation Recipe
+1. Import `InlineDropdown`.
+2. Define `items` and selected state.
+3. Bind with `v-model`.
+4. Use `@itemSelected` when selection triggers additional actions.
+
+## Validation And Edge Cases
+- Keep selected item object identity stable when items refresh.
+- Handle stale selections if option list changes dynamically.
+
+## Definition Of Done
+- Selection updates reliably and inline UX remains compact and clear.

package/src/skills/umbra.ui-control-radio/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: Radio
+
+Use this skill for mutually-exclusive option groups with Umbra `Radio`.
+
+## When To Use
+- Exactly one option must be selected from a set.
+- Settings/forms with clear single-choice decisions.
+- Layouts needing horizontal or vertical radio groups.
+
+## Required Context Checklist
+- `items: ControlItem[]` definitions (title/subtitle/disabled).
+- Selected index source of truth.
+- Layout choice (`horizontal` or `vertical`).
+- Desired visual type via `checkboxType`.
+
+## Ask Developer If Missing
+- "What are the available options and default selection?"
+- "Should options display horizontal or vertical?"
+- "Any options disabled by permission/state?"
+
+## Implementation Recipe
+1. Import `Radio`.
+2. Define options and `selectedIndex`.
+3. Render with `:items`, `:selected-index`, and layout/type props.
+4. Handle `@click` to persist selected index.
+
+## Validation And Edge Cases
+- Ensure selected index stays in bounds when options change.
+- Disabled options should not be selectable.
+- Persist index to domain model when leaving the view.
+
+## Definition Of Done
+- One-and-only-one selection works and maps correctly to business state.

package/src/skills/umbra.ui-control-range-slider/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: RangeSlider
+
+Use this skill for dual-thumb range selection with Umbra `RangeSlider`.
+
+## When To Use
+- Price/age/time filters requiring min/max bounds.
+- Configs where users choose an allowed interval.
+- Range UIs with optional ticks/labels.
+
+## Required Context Checklist
+- Absolute `min`/`max` bounds.
+- Controlled values: `minValue` and `maxValue`.
+- `sliderStyle`, tick interval, and label display expectations.
+- Persistence target for selected range.
+
+## Ask Developer If Missing
+- "What min/max bounds should be enforced?"
+- "Should ticks or tick labels be shown?"
+- "What should happen when range updates?"
+
+## Implementation Recipe
+1. Import `RangeSlider`.
+2. Maintain parent-controlled `minValue` and `maxValue`.
+3. Render with bounds and style props.
+4. Handle `@update:min-value` and `@update:max-value`.
+
+## Validation And Edge Cases
+- Ensure `minValue <= maxValue` at all times.
+- Clamp external values to bounds before passing to component.
+- Verify behavior on touch and mouse.
+
+## Definition Of Done
+- Range updates are stable, bounded, and persisted correctly.