docs(theme): rewrite tokens README to match build-tokens pipeline#562
Merged
Conversation
The README still described the older inject-from-browser pipeline (compile-primitives + compile-theme as the entrypoints) and was out of sync with the file tree. Update it to reflect: - The package now ships dist/v3 (tailwind preset + globals.css) and dist/v4 (CSS-first @theme) artifacts emitted by build-tokens.mjs. - Primitives tree includes animations/, more typography (font-weight, leading, tracking), more effects (drop-shadow, inset-shadow, perspective, shadow), and the colors palette no longer has 'neutral' (removed in bcf7cb4 — gray took over). - Both tokens/theme/ and tokens/semantic/ exist; semantic includes the responsive *.data.js tables consumed by build-tokens.mjs. - Documents how to consume the package in Tailwind v3 (preset + globals.css) and v4 (@import globals.css). - Adds 'responsive semantic token' workflow. - Updates tokenRef path table to match the resolver in scripts/resolve.js (surfacePrimitives entry; primitives.gray references). - Lists tests/tokens.html alongside primitives.html and theme.html. - Describes the three theme-switching strategies the emitted CSS supports (data-theme attr, .dark class, azion-* namespace).
HerbertJulio
approved these changes
May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
O
packages/theme/src/tokens/README.mdainda descrevia a pipeline antiga (compilação direta no browser viacompile-primitives+compile-theme) e a árvore de arquivos divergiu da realidade. Este PR realinha a doc com o estado atual.O que mudou
Pipeline real
scripts/build-tokens.mjs, que emitedist/v3/(preset Tailwind +globals.css) edist/v4/(CSS-first com@theme).compile-primitives.js/compile-theme.js/resolve.js/css-vars.js/refs.jssão listados como blocos de construção usados pelobuild-tokens.mjs, não mais como APIs de runtime.Árvore de arquivos
Corrigida para refletir o estado atual:
tokens/primitives/animations/{animate.js,ease.js}(não constava).typography/agora incluifont-weight,leading,tracking.effects/agora incluidrop-shadow,inset-shadow,perspective,shadow.shape/incluiaspect-video.jseshape.js.neutralremovida da listagem (foi excluída embcf7cb4—grayé o sucessor).tokens/semantic/documentada com as tabelas responsivas*.data.jsconsumidas pelobuild-tokens.mjs.Como consumir
Nova seção explicando:
presets: [import '@aziontech/theme/tailwind-preset/v3']+@import '@aziontech/theme/v3/globals.css'.@import '@aziontech/theme/v4/globals.css'.createCssVars/cssVarsString/injectCssVars.tokenRef
A tabela de prefixos foi atualizada para bater com o
scripts/resolve.jsreal (incluisurfacePrimitives.surface.N, trocaprimitives.neutral.*porprimitives.gray.*).Theme switching
Documenta as três estratégias que o CSS emitido suporta (
[data-theme=…],.dark,.azion azion-*) em vez de só duas.Como adicionar tokens
Adicionada seção "Add a new responsive semantic token" explicando o fluxo via
tokens/semantic/*.data.js, que não existia.Test plan
packages/theme/src/.build:tokens,build:tokens:v3,build:tokens:v4,build:css:v3) conferidos contrapackage.json../tailwind-preset/v3,./v3/globals.css,./v4/globals.css) conferidos contrapackage.json.tokenRefconferidos contrasrc/scripts/resolve.js.