Velvaet

Velvaet est une librairie UI Svelte 5 en rebuild actif.

Le projet vise une surface premium, expressive, sans dépendance de styling, avec une architecture claire :

• tokens CSS
• primitives composables
• composants interactifs
• effets visuels
• patterns documentés

Le but n'est pas d'empiler 270 exports flous. Le but est d'avoir une petite surface fiable, lisible pour les humains comme pour les agents.

État actuel

Velvaet est en phase de rebuild v2.

Il faut donc distinguer :

• l'ambition produit
• la surface réellement fiable aujourd'hui

La surface publique actuelle du repo est volontairement réduite :

• runtime : tokens, primitives, utilitaires et effets surface, light, interaction ;
• composants : Accordion, Avatar, Badge, Button, Calendar, Card, Chat, Checkbox, CheckboxGroup, CodeBlock, CodeDiff, Collapsible, Combobox, DataTable, DatePicker, Dialog, Input, LiquidEther, Markdown, Popover, Progress, RadioGroup, Select, Sheet, Skeleton, Slider, Switch, Tabs, Textarea, Toaster, Toggle, ToggleGroup, Tooltip ;
• helper structurel : velvaet/Form.

Le catalogue historique reste du matériau de rebuild, pas une API publique.

Readiness package

La surface publique n'est considérée fiable que si elle passe le check local :

pnpm run build
pnpm run check:package-readiness
pnpm run smoke:consumer-imports

Ce check vérifie :

• les exports package.json
• les fichiers dist réellement produits
• les fichiers .d.ts
• les dossiers composants src/lib/components
• les subpaths d'effets réellement exportés
• un mini consumer Vite/Svelte qui compile les imports publics critiques

Si package.json annonce un composant mais que dist/components/<Component>/index.js ou index.d.ts manque, le check échoue. Pas d'import fantôme.

Philosophie

Velvaet est :

• Svelte-first
• snippet-first
• token-first
• AI-ready by design

Ce que ça veut dire en pratique :

• pas de Tailwind comme dépendance structurelle
• pas de CSS-in-JS runtime
• pas de composants monolithiques opaques
• pas de fausse abstraction entre design system et code

Le contrat visé est :

• mêmes noms
• mêmes variants
• mêmes slots
• pas de couche de traduction inutile entre design et code

Architecture v2

Velvaet suit une architecture en couches :

1. Layer 0 — Tokens
2. Layer 1 — Primitives
3. Layer 2 — Components
4. Layer 3 — Effects
5. Layer 4 — Patterns

Le détail et les décisions d'architecture vivent dans VELVAET-V2.md.

Snippets et composition

La composition moderne de Velvaet repose sur les Snippets Svelte 5.

Concrètement, des composants comme :

• Button
• Card
• Badge

utilisent déjà des surfaces de composition nommées qui préparent très bien un futur bridge avec Figma/Vaector.

Important :

• tous les Snippet ne sont pas automatiquement des slots Figma exportables
• le bridge doit rester contract-first
• on ne met pas de logique Figma dans le runtime des composants

Bridge futur avec Vaector / Figma

Velvaet reste un bon candidat pour un bridge design-to-code et code-to-design, mais ce bridge n'est plus publié par ce package.

Le repo Velvaet se concentre maintenant sur la lib npm Svelte-first. Si un contract-builder revient, il doit vivre côté Vaector et lire la vérité produit depuis src/lib/metadata/components.ts.

Le principe reste inchangé :

• le code composant gagne sur les manifests
• les composants restent Svelte-first
• aucune logique Figma ne doit entrer dans le runtime Velvaet

Installation

Velvaet se distribue en hybride : un seul npm i velvaet installe le runtime core (tokens, primitives, effets, moteurs) et le CLI velvaet. À partir de là, deux chemins.

npm i velvaet

Importe les tokens une seule fois à la racine de l'app :

<script>
  import 'velvaet/tokens.css';
</script>

Ensuite, soit tu importes un composant directement depuis npm (transition, usage rapide sans customisation) :

<script>
  import { Button, Card, Badge } from 'velvaet';
</script>

soit tu copies son source dans ton projet pour le posséder et l'adapter (pattern shadcn) :

npx velvaet add Button        # copie Button + sa cascade dans src/lib/velvaet/
npx velvaet list              # liste les composants et leurs dépendances
npx velvaet diff Button       # montre ce que tu as modifié vs le registry
npx velvaet update --dry-run  # prévisualise une mise à jour à trois sources

Le code copié t'appartient : l'éditer est le workflow prévu. Committe velvaet.json et .velvaet/base/ pour préserver les mises à jour à trois sources. Le runtime core (velvaet/primitives, velvaet/utils/*) reste toujours npm, jamais copié. Détails et codes de sortie dans AGENTS.md (section Distribution) et la spec Project-Brain/design/specs/distribution-cli.md.

Quick start

<script lang="ts">
  import 'velvaet/tokens.css';
  import { Button, Card, Badge } from 'velvaet';
</script>

<Card title="Premium feel" description="Surface expressive, zéro dépendance de styling.">
  {#snippet footer()}
    <Button variant="primary">Get started</Button>
  {/snippet}
  <Badge variant="success">Ready</Badge>
</Card>

Default Button Variants

Velvaet's default Button hierarchy is:

• primary: bright command surface, #aaaaaa fill with #1c1c1c text.
• secondary: dark filled surface, #1c1c1c fill with #aaaaaa text.
• ghost: transparent, for low-emphasis actions.
• success, warning, error: semantic OKLCH state variants.

<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>

Control Density Contract

Button, Badge, and Toggle share the same compact control baseline:

S height: 24px
S horizontal padding: 8px
content gap: 4px
radius: 4px
outline border: #373737
active/focus border: #aaaaaa
button font-weight: 500
button icon sizes: xs 8px, s 10px, m 12px, l 14px, xl 16px
badge/toggle icon sizes: sm 10px, md 12px, lg 14px

The docs expose the live manifest at /foundations/tokens; do not duplicate token values in downstream project docs.

Direction technique

Velvaet suit maintenant les primitives modernes de Svelte 5 :

• runes
• Snippet
• {@attach} pour les effets, pas use: comme doctrine cible

Le repo n'est donc pas en train de "stabiliser une vieille v1". Il est en train de reformuler le produit sur une base plus propre.

Docs utiles

• ROADMAP.md — état des tracks actifs
• VELVAET-V2.md — architecture et doctrine
• PRODUCT.md — vision produit
• _maelodynn/patterns/component-contract.md — contrat de parité design ↔ code

Ce que README ne prétend plus

Ce README ne raconte plus :

• que tout le catalogue historique est "shippé"
• que la surface actuelle vaut déjà 270 composants fiables
• que le bridge Figma/Vaector est prêt

Le repo vaut mieux qu'un README marketing en roue libre. La direction est forte. Le chantier est encore en cours.