NPM package | CoreAI design system

Let your agent handle setup

Give your agent the package README and ask it to install the package, configure CoreAIFluentProvider, and verify the result.

The provider belongs once at the app root. Import components from @coreai-ds/react-components, not directly from Fluent's component barrel. Icons can still come from @fluentui/react-icons.

Fonts

Aptos is preferred, but font binaries are not included in this repository or the npm package. The optional package font stylesheet registers locally installed fonts; it does not download them. Review the font setup and licensing guidance. Do not commit downloaded fonts. Non-Microsoft-hosted projects must use Inter rather than publishing Aptos files.

Full package reference

The following content is included from the package README during the build, not copied into a second maintained guide. Start with the agent workflow for targeted Markdown documentation lookup.

A custom Fluent UI v9 theme delivered as a drop-in <CoreAIFluentProvider>: brand ramp, light/dark token overrides, Aptos typography, per-component default props, and per-component style hooks. Drop it in place of FluentProvider and your app picks up the entire CoreAI look without touching any of your <Button>, <Input>, <Card>, … call sites.

The package name mirrors @fluentui/react-components because this package wraps and re-exports that API. In most imports, replacing the @fluentui scope with @coreai-ds is all that is needed to adopt the CoreAI Design System.

Install

Install the package from npm:

npm install @coreai-ds/react-components
npm install @fluentui/react-components @fluentui/react-icons # peer dependencies as needed

If your project uses a custom default registry, route the package scope to npm in your .npmrc:

@coreai-ds:registry=https://registry.npmjs.org/

Source, issues, and pull requests are available at microsoft/coreai-design-system. For maintainer publication instructions, see RELEASING.md.

Works with React 18 and 19 (react/react-dom peer range >=16.14.0 <20.0.0, matching Fluent UI v9).

Usage

import { CoreAIFluentProvider, coreaiLightTheme, Button } from '@coreai-ds/react-components';

export function App() {
  return (
    <CoreAIFluentProvider theme={coreaiLightTheme}>
      <Button>OK</Button> {/* shape="circular" — CoreAI default */}
      <Button shape="square">OK</Button> {/* caller props always win */}
    </CoreAIFluentProvider>
  );
}

Import from @coreai-ds/react-components, not @fluentui/react-components. The barrel re-exports every Fluent name; CoreAI-customized components shadow the stock ones, everything else passes through unchanged.
Set withComponentDefaults={false} on the provider to keep CoreAI colors/tokens/style-hooks but use stock Fluent prop defaults (e.g. when nesting a non-CoreAI subtree).

Vite SSR and Vitest

If Node reports ERR_MODULE_NOT_FOUND for @fluentui/react-icons/lib/icons/chunk-0, configure both packages for Vite transformation:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  ssr: { noExternal: ['@coreai-ds/react-components', '@fluentui/react-icons'] },
});

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    server: {
      deps: { inline: ['@coreai-ds/react-components', '@fluentui/react-icons'] },
    },
  },
});

See Vite's ssr.noExternal and Vitest's server.deps.inline.

Font registration

The theme prefers Aptos for proportional and numeric text, then Inter, then system fonts. Monospace text prefers Aptos Mono before system monospace fonts. To recognize Aptos fonts already installed on the user's device, optionally register the local-only @font-face declarations once:

import '@coreai-ds/react-components/fonts/fonts.css';

Applications can load the supported Inter fallback faces (normal and italic at weights 400, 600, and 700) from Google Fonts:

@import url('https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,600;0,700;1,400;1,600;1,700&display=swap');

Only Microsoft-hosted projects may host Aptos font files. Non-Microsoft projects must not self-host Aptos; use the Inter fallback above instead.

Font binaries are not distributed in this package. Applications that need hosted Aptos must be Microsoft-hosted, obtain the fonts under appropriate terms, and provide their own licensed font assets and CSS. The repository's optional local font setup is for authorized local previews, not a license to redistribute; see the font setup and licensing guide.

Overriding styles with CSS Modules or other style systems

Note: An opt-in, app-owned Griffel renderer can wrap runtime-generated component rules in @layer griffel, so normal unlayered CSS Modules override them without specificity hacks. Supply it through RendererProvider above CoreAIFluentProvider; do not patch shared dependencies. Layering is not enabled by this package automatically. The adapter uses Griffel's internal insertion method and needs upgrade checks; extracted static CSS requires separate layering. See Styling with CSS Modules for the implementation, scope, and limits.

Agent guide

Start at the CoreAI Markdown index. Agents use ordinary HTTPS to read guidance, APIs, examples, templates, and package versions. No login, special protocol, or client configuration is needed. See Build with your agent for a starter prompt.

Install the current skill as a reviewable file before CoreAI UI work, or update an older copy already in the consuming repository, such as .github/skills/coreai-ds-fluentui-react/SKILL.md. Other clients can use their supported skills directory, such as .agents/skills/coreai-ds-fluentui-react/SKILL.md or .claude/skills/coreai-ds-fluentui-react/SKILL.md. The starter prompt authorizes this skill's installation/update. Otherwise obtain approval before writing instructions, and ask before resolving conflicts. Preserve existing repository-specific instructions rather than overwriting them.

The skill defines targeted retrieval, version checks, import rules, and safeguards. It does not duplicate component documentation or run downloaded code. Published older package versions may contain older bundled instructions; the current skill download contains the current workflow. Review it before installing.

The description and metadata record the shared docs/skill version separately from the documented package version. Check the small version manifest once per task and refresh older skill guidance; do not downgrade a newer local skill. Documentation-only updates do not require a new component package.

Compare the documented package version with installed packages. Report missing documentation rather than guessing APIs, and review and test examples before using them in an application.

eslint

Forbid the import of @fluentui/* directly in your eslint.config.js so consumers always go through the CoreAI barrel and pick up our wrapped components.

export default [
  {
    rules: {
      // ── No direct @fluentui imports ────────────────────────────────
      // @coreai-ds/react-components re-exports the Fluent UI v9
      // surface and selectively overrides components with CoreAI-themed
      // wrappers (Button, Card, Input, …). Importing directly from @fluentui
      // bypasses those wrappers and your app will render stock Fluent in
      // those spots.
      // @fluentui/react-icons is allowed (icons are consumed directly).
      'no-restricted-imports': [
        'error',
        {
          patterns: [
            {
              group: ['@fluentui/*', '!@fluentui/react-icons'],
              message:
                'Import from "@coreai-ds/react-components" instead of @fluentui directly. ' +
                'The CoreAI barrel wraps Fluent UI components with theme defaults and style hooks. ' +
                'Example: import { Button } from "@coreai-ds/react-components";',
            },
          ],
        },
      ],
    },
  },
];

Microsoft AI Foundry DS

This is based on the original AI Foundry DS - https://brave-field-0ab65a210.6.azurestaticapps.net/

Source layout

Everything lives under src/. Rather than enumerate files here (which drifts as the code changes), browse the directory directly — each file carries a header comment explaining its what and why, and the Architecture notes below link to the files that anchor each pattern.

Architecture notes

Barrel + export * shadowing — see src/index.ts. Stock Fluent surface re-exported first; CoreAI wrappers re-exported by name afterward to shadow the stock names.
withComponentDefaults HoC — see src/contexts/withComponentDefaults.ts.
customStyleHooks_unstable registry — see src/contexts/styleHooks.ts and src/components/Card.styles.ts.
Custom prop-widening wrapper — see src/components/TabList.tsx.
Webpack NormalModuleReplacementPlugin rewrite — Storybook (the playground app) routes Fluent's canonical story imports through this barrel so they pick up CoreAI defaults. See apps/storybook/.storybook/main.ts at the monorepo root.
Complete variation inventory vs stock Fluent — see Variations from Fluent.

Extending CoreAI

Add a default-props wrapper — add a dedicated module under src/components and an explicit named re-export to src/index.ts.
Add a style hook — create src/components/<Component>.styles.ts (see Card.styles.ts) and register it in styleHooks.ts.
Add a prop-widening wrapper — follow the TabList.tsx pattern and export from src/index.ts.

Build

This package is part of a monorepo. From the repo root:

npm ci --ignore-scripts                                          # bootstrap
npm --workspace packages/react-components run build          # tsc -> dist/
npm --workspace packages/react-components run type-check     # tsc --noEmit

The manifest's main, types, and root exports point directly at compiled dist output. Development tools may explicitly alias the package to source; npm does not rewrite entrypoints through publishConfig. Build before packing: the repository disables dependency lifecycle scripts, including automatic prepack. Run npm run test:package --workspace packages/react-components to clean, build, and verify actual tarball exports and the font-free file allowlist.

Testing

Component tests run in Chromium with Vitest Browser Mode. They cover functionality added or changed by CoreAI; they do not retest unchanged Fluent behavior or component appearance.

Test CoreAI-owned behavior such as wrapper defaults, prop transformations, callbacks, state changes, and accessibility semantics. Do not test unchanged Fluent internals, snapshots, CSS values, layout, or visual appearance. Keep tests colocated with their component as src/**/*.test.tsx.

Install the browser once, then run the package tests from the repository root:

npm --workspace packages/react-components run test:install-browser
npm --workspace packages/react-components test

For local development, use test:watch to rerun tests after changes.

Fluent UI support

@fluentui/react-components 9.70.0 is the minimum supported version. It is the first release that supports React 19 and contains every Fluent API currently used or re-exported by this package. @fluentui/react-icons has a minimum supported version of 2.0.316, which satisfies the icon exports required by the Fluent 9.70.0 dependency graph.

The peer dependencies preserve these compatibility floors for consumers. Development dependencies pin the latest Fluent releases exactly so normal development catches upstream changes early. The weekly Fluent update pipeline advances only those development pins and validates the package twice: once against the latest releases and once against the peer minimums.

Releasing

Once enabled, npm publication follows successful CI on the version-changing main commit and creates its version tag after npm verification. Publishing requires package/access review and a protected publishing environment. See RELEASING.md for the publishing controls, publisher setup, tarball verification, and release process.