@wellingtonhlc/shared-ui 0.27.0 → 0.29.0

package/README.md

@@ -168,10 +168,26 @@ import { cn } from '@wellingtonhlc/shared-ui/utils/cn';
 Estilos:
 
 ```tsx
-import '@wellingtonhlc/shared-ui/styles.css';
-```
-
-Preset Tailwind:
+import '@wellingtonhlc/shared-ui/styles.css';
+```
+
+### Foundations e tokens
+
+`styles.css` define os tokens semânticos consumidos pelos componentes. Prefira sempre
+esses tokens a valores locais:
+
+- cores de superfície, texto, borda, marca e estados (`--background`, `--surface`,
+  `--brand`, `--status-*-*`);
+- tipografia (`--font-family-*`, `--font-size-*`, `--line-height-*`);
+- espaçamento (`--space-*`);
+- forma e elevação (`--radius-*`, `--shadow-*`);
+- movimento (`--duration-*`).
+
+O Storybook documenta as escalas em `Foundations` e organiza os exemplos públicos em
+`Components`, por função. Consumidores podem sobrescrever tokens de tema, mas componentes
+não devem introduzir hexadecimais, sombras ou escalas paralelas.
+
+Preset Tailwind:
 
 ```ts
 import sharedUiPreset from '@wellingtonhlc/shared-ui/tailwind-preset';