alouette

Buttons (Button, IconButton, ExternalLinkButton, InternalLinkButton) and pressable surfaces (PressableBox, PressableListItem). variant is contained|outlined|ghost, size is sm|md, accent defaults to brand. Button label is the required text prop (not children); IconButton requires aria-label. Interactive hover/focus/active/disabled states are built in. For async onPress use ActionButton (runs the promise, shows spinner + inline error); Button state ('loading'|'success'|'failed') is the manual escape hatch that overlays a spinner/terminal icon and disables the button. Load when adding buttons or custom pressable elements.

Animate alouette UI two ways: NativeWind transitions (transition-*, duration-*, ease-* on state changes like active:/hover:/focus:) and CSS keyframe presence animations via PresenceOne / PresenceList (animate-slide-in/out, animate-collapse-in/out). exitDurationMs must come from animationDurationsMs so the unmount timer matches the keyframe. Both run on native via react-native-reanimated. Load when adding transitions or enter/exit animations.

Overlays: Modal (controlled by visible/onClose, with title or required aria-label, optional icon/footer, size sm/md/lg, dismiss via backdrop/close/ Escape/Android-back) and AlertDialog for confirmations. AlertDialog variant is confirm (cancel+confirm) | alert (single acknowledge) | required (single action, non-dismissible); accent defaults to danger. Prefer the icon-fixed presets QuestionAlertDialog / WarningAlertDialog / InfoAlertDialog / SuccessAlertDialog. Load when adding a modal, confirmation, or alert dialog.

Open external URLs with ExternalLink (wraps expo-web-browser / Linking) or ExternalLinkButton, configuring openLinkBehavior per platform (native: linking|webBrowser; web: targetBlank|targetSelf). Load when linking out to external URLs from alouette UI.

Semantic message banners: Message (requires accent + icon) and the presets InfoMessage, ConfirmationMessage, WarningMessage, ErrorMessage. Optional dismiss requires onDismiss and dismissIconAriaLabel together; size is sm/md/lg. Also ConnectionState, a top-pinned network-status banner driven by a state prop, and LinearProgress / CircularProgress determinate progress indicators (progress 0-100, accent, size xs/sm/md/lg). Load when showing inline status, alerts, dismissible notices, connection status, or progress.

Forms end to end. Inputs: InputText (mode: password/email/number/tel/url/search), TextArea, Switch (checked + onValueChange; use disabled not editable). Single-select: RadioGroup + Radio (circle-dot list) and RadioButtonGroup + RadioButton (segmented pill bar); controlled/uncontrolled via value/defaultValue/onValueChange + accent/disabled. Validation on react-hook-form: Form owns the instance and exposes submit() via render prop (no control passing); FormField wires Controller to FormItem label/error/required; FormFieldArray wraps useFieldArray with add/remove; FormSubmitButton drives loading/success/failed; SimpleVForm is the vertical-stack shortcut. errorToMessage required (i18n); FormValidationError distinguishes invalid fields from onSubmit failures. Load when building text fields, toggles, radio groups, or a validated form.

Use Phosphor icons with alouette. Import each icon from alouette-icons/phosphor-icons/IconName, then render via the Icon component or pass it to Button / IconButton / Message icon props. Tint with a text-* className (resolved to a color token); size with the numeric size prop. Load when adding icons to alouette UI.

Compose layout with Box / InteractiveBox / SafeAreaBox, Surface (variant/size/shadow), Stack / HStack / VStack, Separator, ScreenCenterLayout, and gradients (GradientBackground / GradientScrollView). Use the alouette spacing (xxs..4xl), radius (xs..lg) and shadow (s/m/l/lowered) scale via p-*/gap-*/rounded-*/shadow-* classes. Load when building screen structure, cards, spacing, or backgrounds.

Build adaptive layouts. Prefer Tailwind responsive variant classes (sm:, md:, lg:, xl:) for responsive styling — they work on web and native. alouette customizes the widths: sm 480, md 768, lg 1024, xl 1280. Fall back to SwitchBreakpointsUsingDisplayNone / SwitchBreakpointsUsingNull (and useCurrentBreakpointName) only when a class can't express the change — a different component tree per size, or unmounting a heavy off-screen variant.

Wire alouette into an Expo / React Native app: withAlouetteConfig metro plugin, import alouette/global.css with @source globs, AlouetteProvider (themeVariables is a required prop — pass the map from alouette/defaultThemeVariables), SafeAreaProvider, and loading Sora / Chivo Mono font weights. Load when bootstrapping a project, when alouette classes render unstyled, or when fonts/bold weights look wrong. Covers ios, android and web.

Re-theme a subtree with accents (brand, danger, info, success, warning) and light/dark modes. Use the accent prop, AccentScope, or ScopedTheme; children always consume base tokens (bg-surface, text-accent, text-sharp, text-muted, border-muted). Read token values in JS with useThemeToken; read the current mode with useCurrentMode. For an accent that toggles at runtime (e.g. on hover) without remounting the subtree, use StableAccentScope instead of AccentScope. Load when applying colors, accents, dark mode, or reading a theme color for a non-className prop.

Style alouette Text and Paragraph entirely via className: combined font family+weight utilities (font-body, font-body-bold, font-body-extrabold, font-heading*, font-mono*), Tailwind text-* sizes, and semantic color tokens (text-sharp, text-muted, text-accent, text-on-accent). No variant props. Load when rendering any text; avoids font-bold and raw color classes.

How to update, reconcile, or add the alouette library skills in packages/alouette/skills (the @tanstack/intent / agentskills.io skills shipped with the package). Use when source components change, on version bumps, or when adding a skill for a new component.

Provides Storybook guidelines for stories, component vs page stories, and testing with play. Use when creating or modifying .stories.tsx files.