Component library for the Aurora Design System, built with React, TypeScript, and Storybook.
@worldline/aurora-react has been tested with React Router v7 and Next.js
16 (App Router).
- Node.js >= 26
- React >= 19
The package is available on a private npm registry (soon to be publicly released on npmjs.com). Install it using npm:
npm install -S @worldline/aurora-reactYou also need to install the required peer dependencies if they are not already present in your project:
npm install -S classnames react-aria-componentsTo properly display Aurora components, import the CSS files in your
application's main entry file — for example, the root layout (app/layout.tsx
in Next.js, app/root.tsx in React Router):
import '@worldline/aurora-react/fonts.css'
import '@worldline/aurora-react/styles.css'styles.css already embeds the design tokens: @worldline/aurora-design-tokens
is inlined at Aurora build time, so do not import
@worldline/aurora-design-tokens/style.css as well — you would ship a duplicate
copy of every --au-* custom property.
This means the token version is frozen at Aurora's build time, while the
JavaScript side (@worldline/aurora-design-tokens/variables) resolves against
whatever your app has installed. Aurora pins the dependency to an exact version
so the two cannot drift; keep that pin exact if you ever change it.
Components are available as named exports from the
@worldline/aurora-react/components entry point:
import { Button, Card } from '@worldline/aurora-react/components'When rendering Aurora components on the server side (SSR), add the following
configuration to your vite.config.ts. Without it, Vite will attempt to process
the CSS files imported by the library's TSX files, which causes build errors:
export default defineConfig({
ssr: {
noExternal: ['@worldline/aurora-react'],
},
// ... rest of the config
})# Install dependencies
npm install
# Start the Vite dev server
npm run dev # http://localhost:5173
# Start Storybook
npm run storybook # http://localhost:6006First-time setup:
npm run test:setup # Install Playwright browser dependenciesRun tests:
npm test # Run all tests in watch mode
npm run test:unit # Unit and component tests only
npm run test:storybook # Storybook interaction tests only
npm run test:visual # Visual regression tests only
npm run test:visual:report # Visual regression tests with HTML report
npm run test:visual:update # Update visual regression baseline screenshots
npm run coverage # Generate coverage reportIcon components are automatically generated from SVG files using SVGR. Icons
under src/assets/icons/basics/ that are part of
Google Material Symbols can be downloaded
using the provided script:
# Download one or more icons (basics directory by default)
npm run icons:download -- heart star music_note
# Download a filled variant (append :fill)
npm run icons:download -- account_circle:fill notifications:fillIcon names must match the Google Material Symbols name (snake_case). Malformed
specs such as name:fill:extra or :fill are rejected with a clear error
message. After downloading, regenerate the React components:
npm run icons:generateThe icon components will also be regenerated automatically when you run
npm run storybook or npm run build.
The public source and package include the pinned, outlined Google Material Symbols in the provenance manifest and the Inter/Raleway fonts. They exclude the internal-only MCC set, filled variants, unverified source vectors, payment-method artwork, file-type artwork, and Worldline logos. The public projection uses pinned Google replacements for selected icons and a CSS tooltip arrow; FileUpload uses a retained document-style icon.
You can make the Storybook accessible to your AI agents by adding the Storybook MCP server to your project. Storybook must be running locally for the server to be available. See the Storybook MCP documentation for details.
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope projectOnce connected, you can prompt your AI agent with requests such as "Show me how to use the Aurora Alert component" or "Create a sign-up form using Aurora components".
| Layer | Technology |
|---|---|
| Framework | React 19 + TypeScript |
| Build tool | Vite (with Rolldown) |
| Testing | Vitest + Playwright |
| Documentation | Storybook v10 |
| Design tokens | @worldline/aurora-design-tokens |
| Versioning | Semantic Release (automated) |
npm run build # Build the library for production
npm run lint # Check code quality
npm run lint:fix # Auto-fix linting issuesReleases are fully automated via the Jenkins pipeline:
developbranch → Semantic Release → Auto-PR tomainmainbranch → Storybook deployed to AWS
See CI_CD_PIPELINE.md for pipeline details.
The Storybook documentation site is deployed to AWS:
- S3 + CloudFront for static hosting
- ACM certificate with custom domains
(
storybook.aurora.example.com) - WAFv2 IP allowlist for access control (office and VPN only)
- Multi-region deployment (us-east-1 for WAF/ACM, eu-west-1 for S3)
See cfn/README.md for the full infrastructure architecture.
| Resource | Description |
|---|---|
| CI/CD Pipeline | Jenkins pipeline stages, branch strategy, and troubleshooting |
| Infrastructure Architecture | CloudFormation stacks, security, and multi-region setup |
| Manual Deployment Guide | Step-by-step infrastructure deployment |