@gouvfr-lasuite/ui-kit

中文文档
0.28.1发布于 2026/07/31TypeScriptESM + CJS近 30 天下载 7218
[![npm version](https://img.shields.io/npm/v/@gouvfr-lasuite/ui-kit.svg)](https://www.npmjs.com/package/@gouvfr-lasuite/ui-kit) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) [
原始使用文档
文档目录59 节
  1. Table of Contents
  2. Introduction
  3. Goals
  4. Features
  5. Technologies
  6. Prerequisites
  7. Installation
  8. Via Yarn (recommended)
  9. Via npm
  10. Peer dependencies
  11. Quick Start
  12. 1. Import styles
  13. 2. Configure the Provider
  14. 3. Use components
  15. Project Structure
  16. Available Components
  17. Layout & Navigation
  18. Forms
  19. Data & Display
  20. Sharing & Collaboration
  21. Integration
  22. Utilities
  23. Themes
  24. Available Themes
  25. Using Themes
  26. Creating a Custom Theme
  27. Hooks
  28. useResponsive
  29. useCustomTranslations
  30. Internationalization
  31. Supported Languages
  32. Changing Language
  33. Contribute to add a language with a new PR
  34. Adding Custom Translations dynamically
  35. Storybook Documentation
  36. Run Storybook Locally
  37. Development
  38. Install Dependencies
  39. Available Scripts
  40. Running Tests
  41. Component Structure
  42. Customization
  43. Design Tokens
  44. CSS Variables
  45. Utility Classes
  46. Usage Examples
  47. Layout with TreeView and Search
  48. Share Modal
  49. Form with Validation
  50. Compatibility
  51. Supported Browsers
  52. Compatible Frameworks
  53. Accessibility
  54. Contributing
  55. Contribution Process
  56. Commit Conventions
  57. Release
  58. License
  59. Support

@gouvfr-lasuite/ui-kit

npm version License: MIT React TypeScript

Official UI Kit for La Suite numérique - A modern, accessible, and customizable React component library built on Cunningham.


Table of Contents


Introduction

@gouvfr-lasuite/ui-kit is the official design system for La Suite numérique, the French government's collaborative tools ecosystem. This library provides a consistent set of reusable, accessible React components that comply with governmental design standards.

Built on top of Cunningham (v4), this kit extends the design system capabilities with components specific to La Suite numérique needs.

Goals

  • Visual Consistency: Ensure a uniform user experience across all La Suite numérique products
  • Accessibility: Comply with WCAG and RGAA standards for maximum accessibility
  • Performance: Optimized and tree-shakable components
  • Flexibility: Support for multiple themes (DSFR, ANCT, White Label)
  • Developer-friendly: Native TypeScript, comprehensive documentation, easy integration

Features

  • 25+ components ready to use
  • Multiple themes: DSFR, ANCT, White Label (light/dark)
  • Accessibility: Keyboard navigation, screen readers, ARIA
  • Internationalization: Built-in French and English support
  • Responsive: Adaptive components with dedicated hooks
  • Layouts: Page layout system with resizable panels
  • La Gaufre Integration: Component for La Suite numérique services integration
  • TypeScript: Full typing for better DX
  • Design tokens: Customizable CSS/SCSS/TS token system

Technologies

TechnologyVersionUsage
React19.xUI Framework
TypeScript5.6Static typing
Vite6.xBundler / Dev server
Cunningham4.1Base design system
Storybook8.5Documentation / Playground
Sass1.83CSS preprocessor
Vitest2.1Unit testing
react-aria-components1.8Accessible primitives
react-resizable-panels2.1Resizable panels
dnd-kit6.3Drag and Drop

Prerequisites

  • Node.js: >= 20.x
  • Package manager: yarn (recommended) or npm
  • React: 19.x

Installation

yarn add @gouvfr-lasuite/ui-kit

Via npm

npm install @gouvfr-lasuite/ui-kit

Peer dependencies

Make sure you have the peer dependencies installed:

yarn add react react-dom

Quick Start

1. Import styles

In your entry file (e.g., main.tsx or App.tsx):

// UI Kit styles (includes Cunningham)
import "@gouvfr-lasuite/ui-kit/style";

// Optional: Marianne font
import "@gouvfr-lasuite/ui-kit/fonts/Marianne";

2. Configure the Provider

Wrap your application with the CunninghamProvider:

import { CunninghamProvider } from "@gouvfr-lasuite/ui-kit";

function App() {
  return (
    <CunninghamProvider>
      <YourApp />
    </CunninghamProvider>
  );
}

3. Use components

import { MainLayout, QuickSearch, TreeView } from "@gouvfr-lasuite/ui-kit";

function MyPage() {
  return (
    <MainLayout
      leftPanelContent={<TreeView data={treeData} />}
    >
      <QuickSearch placeholder="Search..." />
      {/* Your content */}
    </MainLayout>
  );
}

Project Structure

ui-kit/
├── src/
│   ├── components/           # React components
│   │   ├── badge/           # Badge
│   │   ├── button/          # Buttons (ProConnect)
│   │   ├── datagrid/        # Data grid
│   │   ├── dnd/             # Drag and Drop
│   │   ├── dropdown-menu/   # Dropdown menu
│   │   ├── filter/          # Filters
│   │   ├── footer/          # Footer
│   │   ├── form/            # Form fields
│   │   ├── hero/            # Hero section
│   │   ├── icon/            # Icons
│   │   ├── la-gaufre/       # La Suite integration
│   │   ├── language/        # Language selector
│   │   ├── layout/          # Layouts and panels
│   │   ├── loader/          # Loading indicators
│   │   ├── modal/           # Modals
│   │   ├── Provider/        # Cunningham Provider
│   │   ├── quick-search/    # Quick search
│   │   ├── separator/       # Separators
│   │   ├── share/           # Sharing and permissions
│   │   ├── tabs/            # Tabs
│   │   ├── tooltip/         # Tooltips
│   │   ├── tree-view/       # Tree view
│   │   └── users/           # User avatars and menus
│   ├── hooks/               # Custom React hooks
│   ├── locales/             # Translation files
│   ├── styles/              # Global styles and variables
│   ├── assets/              # Resources (fonts, images)
│   └── utils/               # Utilities
├── .storybook/              # Storybook configuration
├── cunningham.ts            # Design tokens configuration
└── dist/                    # Production build

Available Components

Layout & Navigation

ComponentDescription
MainLayoutMain layout with header and resizable panels
HeaderApplication header
LeftPanelLeft side panel (navigation)
RightPanelRight side panel (details)
FooterOfficial footer
TabsTab navigation
DropdownMenuContextual dropdown menu

Forms

ComponentDescription
InputText input field
TextareaMulti-line text area
SelectSelection list
CheckboxCheckbox
RadioRadio button
SwitchToggle switch
LabelField label

Data & Display

ComponentDescription
TreeViewInteractive tree view with pagination
DatagridData grid
QuickSearchQuick search bar (cmd+k)
BadgeStatus badge
IconMaterial icons
LoaderLoading indicator
TooltipTooltip

Sharing & Collaboration

ComponentDescription
ShareModalShare modal with access management
UserAvatarUser avatar
UserMenuUser menu with logout
UsersInvitationUser invitation

Integration

ComponentDescription
LaGaufreLa Suite numérique services menu
LaGaufreV2Enhanced version of La Gaufre
ProConnectButtonProConnect login button

Utilities

ComponentDescription
ModalGeneric modal
SeparatorVisual separator
HeroHero section
FilterFilter component
LanguageSelectorLanguage selector

Themes

The UI Kit supports multiple predefined themes:

Available Themes

ThemeDescription
defaultWhite Label - Light mode
darkWhite Label - Dark mode
dsfr-lightFrench State Design System - Light mode
dsfr-darkFrench State Design System - Dark mode
anct-lightANCT - Light mode
anct-darkANCT - Dark mode

Using Themes

import { CunninghamProvider, cunninghamConfig } from "@gouvfr-lasuite/ui-kit";

// Use a predefined theme
<CunninghamProvider theme="dsfr-light">
  <App />
</CunninghamProvider>

Creating a Custom Theme

see Cunningham docs for more information

Hooks

useResponsive

Detects responsive breakpoints:

import { useResponsive } from "@gouvfr-lasuite/ui-kit";

function MyComponent() {
  const { isMobile, isTablet, isDesktop } = useResponsive();

  return isDesktop ? <DesktopView /> : <MobileView />;
}

useCustomTranslations

Override default translations:

import { useCustomTranslations } from "@gouvfr-lasuite/ui-kit";

// In your Provider
const customTranslations = {
  "en-US": {
    components: {
      share: {
        modalTitle: "Share this document",
      },
    },
  },
};

Internationalization

The UI Kit natively supports French, English, Dutch, German and Spanish.

Supported Languages

  • fr-FR - French (default)
  • en-US - English
  • nl-NL - Dutch
  • de-DE - German
  • es-ES - Spanish

Changing Language

<CunninghamProvider currentLanguage="en-US">
  <App />
</CunninghamProvider>

Contribute to add a language with a new PR

  • Create a new translation file in src/locales
  • Add all translations
  • Create a PR

Adding Custom Translations dynamically

import { locales } from "@gouvfr-lasuite/ui-kit";

const customLocales = {
  ...locales,
  "de-DE": {
    components: {
      share: {
        modalTitle: "Teilen",
        // ...
      },
    },
  },
};

<CunninghamProvider customLocales={customLocales}>
  <App />
</CunninghamProvider>

Storybook Documentation

Interactive documentation is available via Storybook.

Run Storybook Locally

yarn storybook

Then access http://localhost:6006


Development

Install Dependencies

yarn install

Available Scripts

ScriptDescription
yarn devStart Vite development server
yarn buildBuild library for production
yarn lintCheck code with ESLint
yarn testRun tests with Vitest
yarn storybookStart Storybook (port 6006)
yarn build-storybookBuild Storybook for deployment
yarn build-themeGenerate CSS/SCSS/TS token files

Running Tests

# Tests in watch mode
yarn test

# Tests with coverage
yarn test --coverage

Component Structure

src/components/my-component/
├── index.tsx           # Main export
├── index.scss          # Component styles
├── MyComponent.tsx     # React component
├── types.ts            # TypeScript types
└── my-component.stories.tsx  # Storybook stories

Customization

Design Tokens

Design tokens are defined in cunningham.ts and can be overridden:

// Available tokens
{
  globals: {
    font: { sizes, weights, families },
    spacings: { xs, sm, md, lg, xl, ... },
    colors: { brand-*, gray-*, info-*, success-*, warning-*, error-* },
    breakpoints: { xxs, xs, mobile, tablet },
  },
  contextuals: {
    background: {
        semantic: {
            brand: {
                primary: '..'
            }
        }
    }
  }
 
}

CSS Variables

Tokens are exposed as CSS variables:

.my-custom-element {
  color: var(--c--globals--colors--brand-500);
  padding: var(--c--globals--spacings--md);
  font-size: var(--c--globals--font--sizes--lg);
  background: var(--c--contextuals--background--semantic--brand--primary);
}

Utility Classes

<!-- Colors -->
<div class="clr-green-500">Primary text</div>
<div class="bg-success-500">Secondary background</div>

<!-- Spacing -->
<div class="p-md">Medium padding</div>
<div class="m-lg">Large margin</div>

Usage Examples

import {
  CunninghamProvider,
  MainLayout,
  TreeView,
  QuickSearch,
  UserMenu,
} from "@gouvfr-lasuite/ui-kit";
import "@gouvfr-lasuite/ui-kit/style";

const treeData = [
  {
    id: "1",
    name: "Documents",
    children: [
      { id: "1-1", name: "Report.pdf" },
      { id: "1-2", name: "Notes.md" },
    ],
  },
];

function App() {
  return (
    <CunninghamProvider>
      <MainLayout
        icon={<Logo />}
        leftPanelContent={
          <TreeView
            data={treeData}
            onSelect={(node) => console.log(node)}
          />
        }
        rightHeaderContent={
          <UserMenu
            user={{ name: "John Doe", email: "[email protected]" }}
            onLogout={() => {}}
          />
        }
      >
        <QuickSearch
          onSearch={(query) => console.log(query)}
          groups={[
            {
              title: "Recent documents",
              items: [
                { id: "1", label: "Q4 Report" },
                { id: "2", label: "Budget 2024" },
              ],
            },
          ]}
        />
        <main>Main content</main>
      </MainLayout>
    </CunninghamProvider>
  );
}

Share Modal

import { ShareModal } from "@gouvfr-lasuite/ui-kit";

function ShareButton() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Share</button>
      <ShareModal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        members={[
          { id: "1", name: "Marie", email: "[email protected]", role: "editor" },
        ]}
        onAddMember={(user, role) => {}}
        onRemoveMember={(userId) => {}}
        onCopyLink={() => navigator.clipboard.writeText(window.location.href)}
      />
    </>
  );
}

Form with Validation

import { Input, Select, Switch, Label } from "@gouvfr-lasuite/ui-kit";

function ContactForm() {
  return (
    <form>
      <div>
        <Label htmlFor="name">Name</Label>
        <Input id="name" placeholder="Your name" required />
      </div>

      <div>
        <Label htmlFor="department">Department</Label>
        <Select
          id="department"
          options={[
            { value: "hr", label: "Human Resources" },
            { value: "tech", label: "Technology" },
            { value: "admin", label: "Administration" },
          ]}
        />
      </div>

      <div>
        <Switch id="newsletter" />
        <Label htmlFor="newsletter">Subscribe to newsletter</Label>
      </div>
    </form>
  );
}

Compatibility

Supported Browsers

BrowserVersion
ChromeLast 2 versions
FirefoxLast 2 versions
SafariLast 2 versions
EdgeLast 2 versions

Compatible Frameworks

  • React: 19.x (peer dependency)
  • Next.js: 14+ (with appropriate configuration)
  • Remix: Compatible
  • Vite: Optimized

Accessibility

  • WCAG 2.1 Level AA compliant
  • RGAA 4.1 compliant
  • Full keyboard navigation
  • Screen reader support (NVDA, VoiceOver, JAWS)

Contributing

Contributions are welcome! See the CONTRIBUTING.md file for details.

Contribution Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Commit your changes (follow commit conventions)
  4. Push the branch (git push origin feature/my-feature)
  5. Open a Pull Request

Commit Conventions

This project follows conventional commit conventions:

type(scope): description

# Examples
feat(tree-view): add pagination support
fix(modal): resolve focus trap issue
docs(readme): update installation section

Release

See CONTRIBUTING.md for the release process.


License

This project is licensed under the MIT License. See the LICENSE file for details.


Support


Made with care for La Suite numérique
A French government initiative

版本与发布记录

@gouvfr-lasuite/ui-kit 共发布 69 个版本,首次发布于 2025/03/10;过去 12 个月发布了 32 个版本。

版本发布日期距今
0.28.1latest2026/07/313 个月前
0.28.02026/07/283 个月前
0.27.02026/07/084 个月前
0.26.02026/07/034 个月前
0.25.02026/07/014 个月前
0.24.02026/06/294 个月前

关于 @gouvfr-lasuite/ui-kit 的常见问题

@gouvfr-lasuite/ui-kit 是什么?

[![npm version](https://img.shields.io/npm/v/@gouvfr-lasuite/ui-kit.svg)](https://www.npmjs.com/package/@gouvfr-lasuite/ui-kit) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) [

如何安装 @gouvfr-lasuite/ui-kit?

在项目目录运行 npm install @gouvfr-lasuite/ui-kit,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@tanstack/react-query(^5)、react(^19.1.2)、react-dom(^19.1.2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gouvfr-lasuite/ui-kit 支持 TypeScript 吗?

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

@gouvfr-lasuite/ui-kit 支持 ESM 还是 CommonJS?

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

@gouvfr-lasuite/ui-kit 可以商用吗?

@gouvfr-lasuite/ui-kit 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@gouvfr-lasuite/ui-kit 的下载量有多少?

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

@gouvfr-lasuite/ui-kit 还在维护吗?

最新版本 0.28.1 发布于 2026/07/31(3 个月前);至今共发布 69 个版本,其中过去 12 个月发布了 32 个;首次发布于 2025/03/10。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。