@flipova/foundation

中文文档
3.1.0发布于 2026/11/16MITTypeScriptESM + CJS构建来源已验证近 30 天下载 2328

Foundation of the Flipova design system: a provider-agnostic UI contract (57 components), five providers (flipova, gluestack, reusables, paper, tamagui), and a registry-driven theming toolchain with a local GUI.

原始使用文档
文档目录10 节
  1. Quick start
  2. Where things are
  3. The design is yours
  4. npx flipova-design gui
  5. The XML toolchain
  6. How "identical" is tested
  7. Boundary with the frontend
  8. Migrating from 2.x
  9. Documentation
  10. License

@flipova/foundation

npm version License: MIT

UI components for React Native (iOS, Android) and Web, with one design applied to everything. Write <Button> once; choose which library renders it (Flipova's own, gluestack, React Native Reusables, React Native Paper, Tamagui) in one line; the look comes from your own XML themes, which you edit visually with npx flipova-design gui.

Quick start

npm install @flipova/foundation
npx flipova-design adopt     # copies the neutral starter themes into your project, writes theme/provider.tsx
npx flipova-design gui       # edit colours, scales and themes visually (or edit design/*.xml by hand)
npm run design:gen           # -> theme/design-theme.ts (+ Tailwind artifacts)
import { AppThemeProvider } from './theme/provider';
import { Button, Card, Heading, Input, Select, Tabs } from '@flipova/foundation';

export default () => (
  <AppThemeProvider mode="system">
    <Card>
      <Heading>Sign in</Heading>
      <Input placeholder="Email" />
      <Button onPress={signIn}>Continue</Button>
    </Card>
  </AppThemeProvider>
);

theme/provider.tsx is yours: it names the library and hands your generated theme to the components.

<FlipovaProvider adapter={flipova} theme={designTheme} mode={mode}>

Switch library by changing flipova to paper, tamagui, reusables or gluestack (each imported from @flipova/foundation/providers/<name>). Nothing else changes.

Where things are

components/
  theme/          design-theme.ts       generated from your XML: every colour of every theme, every scale
  contract/       what a component is   props (types.ts) + recipes/ (one pure function per component: the exact
                                        colours, radii, spacings, sizes) + theme resolution
  providers/
    provider.tsx  <FlipovaProvider>     mounts one library with one theme
    rn-base/      React Native's own components, shared by every adapter
    flipova/      Flipova's own         all 57 components, built from react-native only, styled only by the recipes
    gluestack/    gluestack-ui         adapter (31 native) + ui/ (the whole gluestack catalogue, as it was)
    reusables/    React Native Reusables  adapter (31 native), NativeWind classes
    paper/        React Native Paper      adapter (31 native)
    tamagui/      Tamagui                 adapter (32 native)
  ui/             the unified components   import { Button } from '@flipova/foundation' (or '/ui')
design/           the XML registries, the schema, and the toolchain (tools/: CLI, generator, checker, GUI)

The unified ui renders, for each component, the one the chosen library offers, with the design applied. When the library does not have it, the flipova provider serves it (and when no provider is mounted at all, flipova with the bundled neutral theme), so there is never a hole.

The contract is the whole gluestack catalogue: 57 components. flipova implements all of them; every other provider implements natively what its library really has and the tests can verify, and the rest is served by flipova. The exact table is COMPONENTS.md (generated), and coverageOf(adapter) tells it in code.

ProviderNativeof which the library's ownof which React Native's (shared)Served by flipova
flipova5743140
gluestack3131026
reusables31191226
paper31171426
tamagui32201225

Every adapter is native for more than half of the contract. "React Native's" are the 14 components that are React Native itself (View, ScrollView, FlatList, SectionList, VirtualizedList, SafeAreaView, KeyboardAvoidingView, StatusBar, RefreshControl, InputAccessoryView, Image, ImageBackground, Pressable, Box): no library replaces them, so they live once in providers/rn-base and every adapter that does not wrap its own serves that one.

Alignment check (components/alignment.test.ts, part of npm test): every directory of the gluestack catalogue must be mapped to a contract name (a new one fails until it is), the mapping is one to one with UI_NAMES, flipova has a file for every name, the unified ui exports every name, adapters declare only names of the contract, and COMPONENTS.md is up to date (npm run components:doc rewrites it).

Honest limits: four gluestack modules (bottomsheet, date-time-picker, image-viewer, slider) cannot be loaded by the test environment (native-only or missing dependencies), so no gluestack wrapper is declared for them. The animation libraries gluestack's overlays use (react-native-reanimated, @legendapp/motion) are replaced in tests by stand-ins in test-support/ (plain views, no animation): what is verified is the gluestack component and its wrapper, not the animation. Components gluestack has but that still fall back (Accordion, Menu, Popover, Select, Tabs, Toast, Tooltip...) are listed with the reason in COMPONENTS.md; adding a wrapper is: write it in the adapter, add it to its components, npm run components:doc.

Props are the same on every provider (components/contract/types.ts). Icons are text glyphs (no SVG dependency), Calendar and DateTimePicker work on dates only (YYYY-MM-DD), and Portal content is drawn by the flipova provider's host.

To go straight to one library's own components, import from its sub-path (@flipova/foundation/providers/paper, .../providers/gluestack/ui for the whole gluestack catalogue, ...). Only that sub-path imports the library, which is an optional peer dependency: the root, /ui, /contract, /providers and /providers/flipova need nothing but react and react-native.

Sub-pathLibraryOptional peer
@flipova/foundation , /uithe unified componentsnone
@flipova/foundation/providers/flipovaFlipova's ownnone
@flipova/foundation/providers/gluestackgluestack-uinativewind
@flipova/foundation/providers/reusablesReact Native Reusables@rn-primitives/switch
@flipova/foundation/providers/paperReact Native Paperreact-native-paper
@flipova/foundation/providers/tamaguiTamagui@tamagui/core

The design is yours

The package ships no brand and no theme names: only a neutral starter (light and dark). adopt copies it into design/ and from then on the registries are your source of truth. The components read colour roles (primary, card, border, success, ...), never theme ids, so rename, add and recolour themes freely; a light/dark pair shares a variant (<FlipovaProvider variant="brand">). A theme must define the roles the components read (REQUIRED_ROLES); the GUI, flipova-design check on save, and the provider all name any that are missing.

  • Tokens (design/tokens.xml): colour palettes, spacing, radii, type sizes and weights, shadows, opacity, motion.
  • Themes (design/themes.xml): each theme maps roles to palette colours ($ref.tokens.color.primary.600) or to a literal colour.

npx flipova-design gui

A local editor (nothing leaves your machine; it listens on 127.0.0.1 with a one-time token):

  • Preview: every component, drawn from the real recipes, in the theme you pick, updated as you edit.
  • Colours: edit any shade; build a whole palette from one colour; add or remove colours.
  • Scales: spacing, radii, font sizes, weights, line heights, opacity, durations, z-index, breakpoints.
  • Themes: add (copy), rename, change mode/variant, delete; map every role to a colour with a picker.
  • Edits live in a working copy. Save validates first (determinism rules, XSD, required roles), then writes your XML, the canonical index and the generated files. Revert drops the working copy.
  • The preview needs the built package (dist/); the published package has it.

Edits are made in the text of the XML (comments and layout are kept), so the diff is what a careful hand edit would give.

The XML toolchain

Plain Node (>= 18, no dependency, no Python): npx flipova-design <command>.

CommandWhat it does
initinject app-level wiring (Tailwind/PostCSS/CSS files, design:* scripts); never overwrites
adoptcopy the registries into the project, rewrite the outputs into theme/, write theme/provider.tsx
gui [--port N] [--no-open]the visual editor (adopts first if the project has not)
gen [--check]compile the registries into design-theme.ts, config.ts, tokens.js
check, verify, canonical, lintdeterminism rules, canonical index, XSD
pipelinegen, check, verify, lint
whereprint the resolved paths

design/schema.xsd is validated by a built-in validator for the subset of XML Schema the registries use; a schema that uses anything else is refused when loaded rather than half-checked. Never hand-edit the generated files; and tailwind.config.js holds no design value: it only wires theme/tokens.

// tailwind.config.js (only needed for the gluestack / reusables providers, which use NativeWind classes)
const tokens = require('./theme/tokens');
module.exports = { presets: [require('nativewind/preset')], theme: { extend: tokens.theme } };

The flipova, Paper and Tamagui providers read theme/design-theme.ts directly; the gluestack and reusables providers build their CSS variables at runtime from the same theme you pass to <FlipovaProvider>.

How "identical" is tested

Parity is on the resolved style values, not on pixels. npm test runs the toolchain tests (including a real adopt, a real GUI server driven over HTTP, and the XML edits), the boundary check, and the component tests: Reusables classes resolved back to numbers and colours and compared with the recipes; the props handed to Paper; the Tamagui configuration; every recipe on every theme (no undefined or NaN value); the 57 flipova components rendered through react-native-web (interaction, accessibility attributes, the app's own theme applied, no colour literal in their source); the six shared components of the four libraries rendered in light and dark; and the natives each library gained rendered through its adapter. Not covered: rendering on a device, and the internals Paper imposes on its own Button and Switch (ripple, switch geometry): what is guaranteed there is what is passed to them.

Boundary with the frontend

Foundation is the bottom of the stack: primitives and the design. Layouts, sections, auth screens, mockups and effects live in the frontend package, and foundation depends on no other @flipova/* package. npm run boundary (run by npm test and CI) reads the imports and fails on: another @flipova/* import; a frontend folder under components/; a layer importing one above it (theme < contract < providers < ui, where ui reaches only the flipova provider); a provider importing another; an optional peer imported outside its own provider; the flipova provider importing anything but react and react-native.

Migrating from 2.x

  • @flipova/foundation and /ui now export the unified components (Button, Card, ...). The gluestack catalogue (Box, VStack, Accordion, ...) moved to @flipova/foundation/providers/gluestack/ui.
  • createGluestackUIProvider and GluestackUIProvider are there too; <FlipovaProvider adapter={gluestack}> replaces them for new code.
  • The package no longer ships the spring theme; add your own with the GUI.
  • @flipova/foundation/tokens is unchanged.

Documentation

  • DOCS.md: the maintainer guide (setup, architecture, tests, releasing, conformity).
  • COMPONENTS.md: the generated coverage table of the five providers.
  • Public documentation: documentation/v1.0/ (French, written from the public templates of flipova.assets with corral docs) published as a Docusaurus site from website/ (corral docs docusaurus --repo foundation).
  • npm run docs:check keeps all of the above consistent with the code (see DOCS.md).

License

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

版本与发布记录

@flipova/foundation 共发布 38 个版本,首次发布于 2026/06/13;过去 12 个月发布了 38 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.1.0latest2026/11/16今天
3.0.02026/11/16今天
3.0.0-rc.3rc2026/11/16今天
3.0.0-rc.22026/11/16今天
3.0.0-rc.12026/11/133 天前
3.0.0-beta.1beta2026/11/133 天前

其他发布通道:alpha → 3.0.0-alpha.1,beta → 3.0.0-beta.1,rc → 3.0.0-rc.3。

关于 @flipova/foundation 的常见问题

@flipova/foundation 是什么?

Foundation of the Flipova design system: a provider-agnostic UI contract (57 components), five providers (flipova, gluestack, reusables, paper, tamagui), and a registry-driven theming toolchain with a local GUI.

如何安装 @flipova/foundation?

在项目目录运行 npm install @flipova/foundation,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=18.0.0)、react-native(>=0.72.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 flipova-design,可以用 npx flipova-design 直接运行。

@flipova/foundation 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@flipova/foundation 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@flipova/foundation 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@flipova/foundation 可以商用吗?

@flipova/foundation 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@flipova/foundation 的下载量有多少?

根据 npm 官方下载统计,@flipova/foundation 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,328 次,日均约 78 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@flipova/foundation 还在维护吗?

最新版本 3.1.0 发布于 2026/11/16(今天);至今共发布 38 个版本,其中过去 12 个月发布了 38 个;首次发布于 2026/06/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。