alouette 19.0.0-beta.3 → 19.0.0-beta.4

package/README.md

@@ -3,7 +3,7 @@
 </h1>
 
 <p align="center">
-  A modern, customizable design system built on top of Tamagui with configurable defaults
+  A modern, customizable design system built on top of NativeWind v5 with configurable defaults
 </p>
 
 <p align="center">
@@ -13,78 +13,196 @@
   <a href="https://npmjs.org/package/alouette"><img src="https://img.shields.io/npm/types/alouette.svg?style=flat-square" alt="types"></a>
 </p>
 
+Alouette provides a comprehensive set of universal components that render on both
+web and React Native, styled entirely through Tailwind `className` via
+[NativeWind v5](https://www.nativewind.dev/). Themes, accents, and design tokens
+ship as CSS custom properties that cascade through the tree, so components stay
+declarative and consistent across platforms.
+
 ## 🚀 Getting Started
 
 ### Prerequisites
 
-- Node.js >= 20.9.0 (includes Corepack for package management)
+- Node.js >= 22.18.0 (includes Corepack for package management)
+- A React Native / Expo app using Metro, or a web app using NativeWind v5
 
 ### Installation
 
-1. Enable Corepack (if not already enabled):
-
 ```bash
-corepack enable
+npm install alouette
+# or with yarn
+yarn add alouette
 ```
 
-2. Install the package:
+`alouette-icons` is installed automatically as a dependency.
+
+Install the peer dependencies if your app does not already provide them:
 
 ```bash
-npm install alouette
-# or with yarn
-yarn add alouette
+npm install nativewind@5.0.0-preview.4 tailwindcss@^4 \
+  react-native-reanimated react-native-svg
 ```
 
-Note: `alouette-icons` is automatically included as a dependency.
+`expo-web-browser`, `react-dom`, and `react-native-reanimated` are optional peers
+— add them only if your target needs them (`react-dom` for web, `react-native-reanimated`
+for native animations, `expo-web-browser` for `ExternalLink`).
 
 ### Configuration
 
-Create or update your `tamagui.config.ts`:
+Alouette relies on NativeWind v5's Metro + PostCSS pipeline. NativeWind discovers
+themes and utilities from the imported `global.css` and scans your sources via
+`@source` directives — there is no JS config to maintain.
+
+1. **Metro** — wrap your config with the Alouette helper:
+
+```js
+// metro.config.cjs
+const { withAlouetteConfig } = require("alouette/metro");
+const { getDefaultConfig } = require("expo/metro-config.js");
+
+module.exports = withAlouetteConfig(getDefaultConfig(__dirname));
+```
+
+2. **CSS entry** — create a `global.css` that re-exports Alouette's tokens and
+   points `@source` at the directories NativeWind should scan for class names:
+
+```css
+/* global.css */
+@import "alouette/global.css";
+
+@source './src'; /* your own className / tv() literals */
+@source '../node_modules/alouette/src'; /* alouette's source — required */
+```
+
+Tailwind only emits classes it finds while scanning `@source` paths, so both
+your app's source **and** alouette's source must be covered or the matching
+utilities are silently purged. In a monorepo where alouette is hoisted to the
+repo root `node_modules`, adjust the depth (e.g.
+`@source '../../../node_modules/alouette/src'`); a path that resolves to nothing
+fails silently with no error.
+
+Import it once at your app's entry point:
 
 ```ts
-import {
-  createAlouetteTamagui,
-  defaultColorScales,
-  createAlouetteTokens,
-  createAlouetteThemes,
-} from "alouette/createAlouetteTamagui";
+import "./global.css";
+```
+
+3. **PostCSS** — NativeWind compiles Tailwind through PostCSS on both web and
+   native. `@tailwindcss/postcss` ships as a dependency of `alouette`, so you
+   only add the config file (use `.mjs` so it loads as ESM regardless of your
+   package's `"type"`):
+
+```js
+// postcss.config.mjs
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+```
+
+4. **Babel** — use the Expo preset and the Reanimated/worklets plugin:
+
+```js
+// babel.config.js
+export default function (api) {
+  api.cache(true);
+  return {
+    presets: [["babel-preset-expo", { reanimated: false }]],
+    plugins: ["react-native-worklets/plugin"],
+  };
+}
+```
+
+5. **Provider** — wrap your app in `AlouetteProvider`. It applies the OS
+   light/dark scheme as the root theme so base tokens resolve app-wide:
+
+```tsx
+import { AlouetteProvider } from "alouette";
 
-const tokens = createAlouetteTokens(defaultColorScales);
-const config = createAlouetteTamagui(tokens, createAlouetteThemes(tokens));
+export function App() {
+  return <AlouetteProvider>{/* your app */}</AlouetteProvider>;
+}
+```
 
-export default config;
+6. **Fonts** — Alouette's typography uses Sora (body/heading) and Chivo Mono
+   (mono). On native, load the weight-specific font files (the standalone
+   `font-weight` utility has no effect because each weight is a distinct file):
+
+```tsx
+import {
+  Sora_400Regular as SoraRegular,
+  Sora_700Bold as SoraBold,
+  Sora_800ExtraBold as SoraExtraBold,
+  useFonts,
+} from "@expo-google-fonts/sora";
+import {
+  ChivoMono_400Regular as ChivoMonoRegular,
+  ChivoMono_700Bold as ChivoMonoBold,
+  ChivoMono_800ExtraBold as ChivoMonoExtraBold,
+} from "@expo-google-fonts/chivo-mono";
+
+const [fontsLoaded] = useFonts({
+  SoraRegular,
+  SoraBold,
+  SoraExtraBold,
+  ChivoMonoRegular,
+  ChivoMonoBold,
+  ChivoMonoExtraBold,
+});
 ```
 
 ## 🎨 Core Features
 
 ### Components
 
-Alouette provides a comprehensive set of components following the atomic design pattern:
+Alouette ships a universal component set styled through `className`:
 
-#### Actions
+- **Actions** — `Button`, `ExternalLinkButton`, `InternalLinkButton`, `IconButton`
+- **Containers** — `Box`, `InteractiveBox`, `SafeAreaBox`, `Surface`, `ScopedTheme`, `AccentScope`, `PresenceOne`, `PresenceList`
+- **Inputs** — `InputText`, `TextArea`, `Switch`
+- **Feedback** — `Message`, `InfoMessage`, `ConfirmationMessage`, `WarningMessage`
+- **Data** — `PressableBox`, `PressableListItem`
+- **Layout** — `GradientBackground`, `GradientScrollView`
+- **Primitives** — `View`, `Text`, `Paragraph`, `Icon`, `ScrollView`, `Stack`, `HStack`, `VStack`, `Separator`
+- **Responsive** — `SwitchBreakpointsUsingDisplayNone`, `SwitchBreakpointsUsingNull`, `useCurrentBreakpointName`
 
-- `Button`: brand interaction component with multiple variants
-- `IconButton`: Circular button optimized for icon display
+For detailed examples and API documentation, visit our [Storybook](https://www.chromatic.com/library?appId=679f9e8df3edc5f07975b64a).
 
-#### Containers
+### Text styling
 
-- `Box`: Basic layout container with theme support
-- `PressableBox`: Interactive container with press states
+`<Text>` has no variant props — style it entirely via `className`. Family and
+weight are combined into a single utility (`font-body`, `font-body-bold`,
+`font-heading-extrabold`, `font-mono`, …); size uses standard Tailwind
+`text-*`; color uses tokens like `text-sharp`, `text-muted`, `text-accent`.
 
-#### Forms
+```tsx
+import { Text } from "alouette";
 
-- `InputText`: Text input with theming and state management
+<Text className="text-base">Body</Text>;
+<Text className="font-heading-extrabold text-4xl">Title</Text>;
+<Text className="font-mono text-xs text-muted">Code</Text>;
+```
 
-#### Layout
+### Theming and accents
 
-- `Separator`: Visual divider with customizable orientation
-- `List`: Structured data display components
+Themes are sets of CSS variables (`light`, `dark`, `light_brand`, `dark_info`, …)
+applied by `ScopedTheme`. Child components use **base tokens** (`bg-surface`,
+`text-accent`, `border-muted`, …) and inherit the correct values from the nearest
+theme scope. Components that introduce an accent wrap their children in
+`AccentScope`:
 
-For detailed examples and API documentation, visit our [Storybook](https://www.chromatic.com/library?appId=679f9e8df3edc5f07975b64a).
+```tsx
+import { AccentScope, Surface } from "alouette";
+
+<AccentScope accent="info">
+  <Surface>{/* children use base tokens */}</Surface>
+</AccentScope>;
+```
 
 ### Icons
 
-Icons are provided through the integrated `alouette-icons` package:
+Icons come from the integrated `alouette-icons` package:
 
 ```tsx
 import { ArrowLeftRegularIcon } from "alouette-icons/phosphor-icons/ArrowLeftRegularIcon";
@@ -94,24 +212,6 @@ function MyComponent() {
 }
 ```
 
-## 🏗️ Architecture
-
-### Core Principles
-
-1. **Universal Design**: Components work seamlessly across web and native platforms
-2. **Performance First**: Optimized bundle size and runtime performance through Tamagui
-3. **Accessibility**: WCAG 2.1 compliant components with proper ARIA attributes
-4. **Customization**: Flexible theming system with sensible defaults
-5. **Type Safety**: Built with TypeScript for enhanced developer experience
-
-### Technical Architecture
-
-- **Component Structure**: Atomic design pattern with atoms, molecules, and organisms
-- **Styling System**: Tamagui's compile-time styling with runtime fallbacks
-- **Theme System**: Token-based design system with support for light/dark modes
-- **Responsive Design**: Mobile-first approach with flexible breakpoint system
-- **Icon System**: Based on Phosphor Icons with optimized bundle size
-
 ## 🎯 Examples
 
 ### Basic Button
@@ -121,11 +221,7 @@ import { Button } from "alouette";
 
 function MyComponent() {
   return (
-    <Button
-      theme="brand"
-      text="Click me"
-      onPress={() => console.log("Clicked!")}
-    />
+    <Button accent="brand" text="Click me" onPress={() => console.log("Clicked!")} />
   );
 }
 ```
@@ -137,15 +233,30 @@ import { Button } from "alouette";
 import { ArrowLeftRegularIcon } from "alouette-icons/phosphor-icons/ArrowLeftRegularIcon";
 
 function MyComponent() {
-  return (
-    <Button theme="brand" icon={<ArrowLeftRegularIcon />} text="Go Back" />
-  );
+  return <Button accent="brand" icon={<ArrowLeftRegularIcon />} text="Go Back" />;
 }
 ```
 
-## 📚 Documentation
+## 🤖 Using an AI agent?
+
+Alouette ships [skills](https://www.npmjs.com/package/@tanstack/intent) that teach
+AI coding agents how to use the design system correctly:
 
-For more examples and detailed documentation:
+```bash
+npx @tanstack/intent@latest install
+```
+
+## 🏗️ Architecture
+
+- **Universal Design** — components render across web and native from one API
+- **NativeWind v5 styling** — Tailwind `className`; animations are CSS
+  `@keyframes` + `--animate-*` tokens, run on native via Reanimated
+- **Token-based theming** — CSS custom properties cascade through `ScopedTheme`;
+  light/dark + accent scopes
+- **Accessibility** — proper ARIA / accessibility attributes
+- **Type Safety** — built with TypeScript
+
+## 📚 Documentation
 
 - [Component Documentation](https://www.chromatic.com/library?appId=679f9e8df3edc5f07975b64a)
 - [GitHub Repository](https://github.com/christophehurpeau/alouette)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alouette",
-  "version": "19.0.0-beta.3",
-  "description": "A modern, customizable design system built on top of Tamagui with configurable defaults",
+  "version": "19.0.0-beta.4",
+  "description": "A modern, customizable design system built on top of NativeWind v5 with configurable defaults",
   "keywords": [
     "tanstack-intent"
   ],
@@ -123,6 +123,7 @@
     }
   },
   "dependencies": {
+    "@tailwindcss/postcss": "4.3.1",
     "alouette-icons": "8.0.7",
     "expo-web-browser": "~15.0.10",
     "react-native-safe-area-context": "5.6.2",

package/skills/alouette-setup/SKILL.md

@@ -8,9 +8,10 @@ description: >
   fonts/bold weights look wrong. Covers ios, android and web.
 type: lifecycle
 library: alouette
-library_version: "19.0.0-beta.1"
+library_version: "19.0.0-beta.3"
 sources:
   - "christophehurpeau/alouette:packages/storybook-native-app/metro.config.cjs"
+  - "christophehurpeau/alouette:packages/storybook-native-app/postcss.config.mjs"
   - "christophehurpeau/alouette:packages/storybook-native-app/src/global.css"
   - "christophehurpeau/alouette:packages/storybook-native-app/src/App.tsx"
   - "christophehurpeau/alouette:packages/alouette/src/core/AlouetteProvider.tsx"
@@ -19,10 +20,10 @@ sources:
 
 # alouette — Setup
 
-alouette is styled with NativeWind v5 / Tailwind CSS v4. An app needs four
-things wired before any component renders correctly: the metro plugin, the CSS
-entry with source globs, the provider, and the fonts. Everything targets
-ios/android/web from the same code.
+alouette is styled with NativeWind v5 / Tailwind CSS v4. An app needs five
+things wired before any component renders correctly: the metro plugin, the
+PostCSS config, the CSS entry with source globs, the provider, and the fonts.
+Everything targets ios/android/web from the same code.
 
 ## Setup
 
@@ -37,14 +38,39 @@ const config = getDefaultConfig(__dirname);
 module.exports = withAlouetteConfig(config);
 ```
 
-`src/global.css` (imported once, at the app entry):
+`postcss.config.mjs` at the **app package root** — this is what actually runs
+Tailwind. `@tailwindcss/postcss` ships as a dependency of `alouette`, so apps do
+not install it; they only add this config file:
+
+```js
+export default { plugins: { "@tailwindcss/postcss": {} } };
+```
+
+Use the `.mjs` extension so it loads as ESM regardless of the package's `"type"`
+field.
+
+`src/global.css` (imported once, at the app entry). Add an `@source` for
+**alouette's source** and one for **your own app source** — both are scanned
+independently of the JS bundle, and anything not covered is purged:
 
 ```css
 @import "alouette/global.css";
 
-@source "../node_modules/alouette/src";
+@source "./**/*.{ts,tsx}"; /* the app's own className / tv() literals */
+@source "../node_modules/alouette/src/**/*.{ts,tsx,js}"; /* alouette source */
 ```
 
+In a monorepo where alouette is hoisted to the **repo root** `node_modules`
+(Yarn `node-modules` linker, pnpm hoisted, etc.), the path resolves from the
+repo root, not the app — adjust the depth accordingly:
+
+```css
+@source "../../../node_modules/alouette/src/**/*.{ts,tsx,js}";
+```
+
+A wrong glob matches zero files and fails **silently** (no error) — utilities
+are simply purged and components render unstyled.
+
 App entry — load fonts (native), then wrap the tree in `AlouetteProvider`:
 
 ```tsx
@@ -136,9 +162,31 @@ Append `&family=Chivo+Mono:wght@400;700;800` to the URL if you use `font-mono`.
 
 ## Common Mistakes
 
-### CRITICAL global.css missing @source for alouette source
+### CRITICAL Missing postcss.config — Tailwind never runs
 
-Wrong:
+Symptom: components render unstyled (only alouette's hotpink `body` fallback
+shows), and the build logs spam `Warning: Unknown at rule: @utility` /
+`@source` / `@theme`. Those warnings are the diagnostic signature — Tailwind
+directives are reaching lightningcss un-expanded because Tailwind never ran.
+
+Mechanism: `withAlouetteConfig` → `withNativewind` delegates CSS compilation to
+Expo's Metro transform worker, which runs Tailwind **only if it finds a
+`postcss.config` file at the project root**. Absent → CSS passes straight to
+lightningcss verbatim and zero utilities are emitted.
+
+Fix — add `postcss.config.mjs` at the app package root:
+
+```js
+export default { plugins: { "@tailwindcss/postcss": {} } };
+```
+
+`@tailwindcss/postcss` is a dependency of `alouette`, so no install is needed.
+
+Source: packages/storybook-native-app/postcss.config.mjs
+
+### CRITICAL global.css missing @source, or wrong path in a monorepo
+
+Wrong (no `@source`, or a path that resolves to nothing):
 
 ```css
 @import "alouette/global.css";
@@ -149,12 +197,25 @@ Correct:
 ```css
 @import "alouette/global.css";
 
-@source "../node_modules/alouette/src";
+@source "./**/*.{ts,tsx}"; /* the app's own classes */
+@source "../node_modules/alouette/src/**/*.{ts,tsx,js}"; /* alouette source */
 ```
 
-Tailwind v4 only emits classes it finds in scanned files. Without an `@source`
-covering alouette's source, every alouette utility class is purged and
-components render unstyled.
+Tailwind v4 only emits classes it finds in scanned files. Two failure modes,
+both producing the same silent unstyled result with **no error**:
+
+1. No `@source` for alouette's source → every alouette utility is purged.
+2. No `@source` for the app's own source → the app's own classes (e.g.
+   arbitrary values like `from-[#f39c12]`, `bg-linear-to-t`) are purged while
+   alouette's still work — easy to misdiagnose.
+3. In a monorepo where alouette is hoisted to the **repo root**
+   `node_modules`, `../node_modules/alouette/src` resolves to nothing. Use the
+   correct depth, e.g. `@source "../../../node_modules/alouette/src/**/*.{ts,tsx,js}"`.
+
+Note: `@source` is a text-scan of alouette's shipped `src/*.tsx` (the verbatim
+`className` / `tv()` string literals) — independent of the JS bundle, which
+Metro resolves to the compiled `dist`. The two pipelines are decoupled, which is
+why the scan targets `src` and not the build output.
 
 Source: packages/storybook-native-app/src/global.css
 

package/src/global.css

@@ -616,6 +616,12 @@
 
   /* let height/width keyframes interpolate to/from auto (collapse-in/out) on web */
   :root { interpolate-size: allow-keywords; }
+
+  body, #root {
+    display: flex;
+    flex-direction: column;
+    min-height: 100vh;
+  }
 }
 
 /* keyframes referenced by the --animate-* theme tokens above. */