@flipova/foundation

gluestack-ui components for React Native (iOS, Android) and Web, plus a registry-driven theming pipeline.

Design pipeline

The design pipeline has a single function:

design/tokens.xml + design/themes.xml

• -> components/ui/gluestack-ui-provider/config.ts (gluestack / nativewind colour vars)
• -> components/ui/gluestack-ui-provider/tokens.js (Tailwind/nativewind token theme)

Role ids in themes.xml are the gluestack CSS variable names (dash-prefixed at generation time), so the design registry and the runtime theme config always speak the same language. Every colour is emitted as a space-separated RGB triplet, enabling Tailwind opacity modifiers such as bg-primary/50.

The scale tokens (spacing, radii, breakpoints, typography, shadow, z-index, opacity, motion) are emitted as a Tailwind theme fragment, and the semantic colours are derived from the themes.xml roles. tailwind.config.js contains no design value: it just does extend: tokens.theme. The XML registries are therefore the single source of truth for both the gluestack runtime vars and the Tailwind/nativewind theme.

npm run design:pipeline   # gen + check + verify + lint + doc

| Script | What it does | | :------------------------- | :--------------------------------------------------- | | npm run design:gen | compile tokens/themes into config.ts + tokens.js | | npm run design:gen:check | verify regeneration is a no-op (drift check) | | npm run design:check | determinism rules + XSD pass + ruff | | npm run design:verify | verify the committed canonical index | | npm run design:canonical | re-emit design/canonical.index.txt | | npm run design:lint | XSD-validate every design XML | | npm run design:doc | regenerate the docs site (docs/generated) | | npm run design:edit | open the XSD-driven XML editor |

Never hand-edit the generated config.ts, tokens.js or docs/generated/** - the next run overwrites them. And never add a design value to tailwind.config.js: it only wires the generated theme.

Install

npm install @flipova/foundation
npm install gluestack-ui
npx flipova-design init

init does not copy the registries into your project. The XML registries and the whole toolchain stay in node_modules/@flipova/foundation/design, and the command only injects the app-level wiring that the package cannot own:

• tailwind.config.js, postcss.config.js, globals.css - created only when missing (never overwritten unless --force);
• the design:* npm scripts in your package.json (design:gen, design:lint, design:check, design:verify, design:canonical, design:doc, design:pipeline).

| Command | What it does | | :--------------------------------- | :---------------------------------------------------- | | npx flipova-design where | print the resolved registries/artifacts paths | | npx flipova-design inject | re-run the injection only | | npx flipova-design adopt | copy the registries into the project and own them | | npx flipova-design gen [--check] | compile the registries into config.ts + tokens.js | | npx flipova-design lint | XSD-validate the registries |

gen writes into the resolved output root, i.e. straight into the installed package (node_modules/@flipova/foundation/components/ui/gluestack-ui-provider), so the artifacts consumed by @flipova/foundation/tokens and @flipova/foundation/ui are always the ones the pipeline produced.

Own the design system

An app that wants its own branding adopts the registries:

npx flipova-design adopt

That copies manifest.xml, schema.xsd, tokens.xml, themes.xml, documentation.xml and canonical.index.txt into design/ - and not the toolchain, which stays in node_modules. It rewrites the manifest outputs to theme/config.ts and theme/tokens.js, and creates theme/provider.tsx.

From then on the project is the source of truth:

# edit design/tokens.xml and design/themes.xml - the colours, the scales, the roles
npm run design:gen        # -> theme/config.ts + theme/tokens.js
npm run design:verify     # the registries are in step with the artifacts
npm run design:check      # determinism + XSD, on YOUR registries

Wire the two artifacts into the app:

// tailwind.config.js
const tokens = require('./theme/tokens');
module.exports = { presets: [require('nativewind/preset')], theme: { extend: tokens.theme } };

// theme/provider.tsx (generated by adopt)
import { createGluestackUIProvider } from '@flipova/foundation/ui';
import { config } from './config';
export const AppThemeProvider = createGluestackUIProvider(config);

The package still provides the components, the generator and every token the app does not override. npx flipova-design where always says which side is in charge.

The generated theme is wired into your Tailwind config (app-level files are not shipped by the package):

// tailwind.config.js
const tokens = require('@flipova/foundation/tokens');
module.exports = {
  presets: [require('nativewind/preset')],
  theme: { extend: tokens.theme },
};

and the provider is mounted once at the root:

import { GluestackUIProvider } from '@flipova/foundation/ui';
// <GluestackUIProvider mode="system"> ... </GluestackUIProvider>

The design tooling needs Python 3.8+ with lxml (design/tools/requirements.txt). Resolution order: $FOUNDATION_PYTHON, then $FOUNDATION_VENV, then design/tools/.venv, then any python3/python on PATH that can import lxml.

Documentation

The full guide (installation, theming, tokens, the gluestack config, tools, contributing) is generated from design/documentation.xml into the Docusaurus site under docs/:

cd docs && npm start

License

MIT © Flipova. Participation is governed by the Code of Conduct.