Locker Design System

Locker Design System provides the shared React components, design tokens, and theming defaults used across Locker products. It builds on Ant Design while preserving Locker's visual language and accessible interaction defaults.

Requirements

• React 18.2 through 19.x
• React DOM 18.2 through 19.x
• A modern browser supported by Ant Design 6
• Node.js 20.19.x, or Node.js 22.12 or later, for development and builds

Installation

Install the design system and its React peer dependencies:

npm install @lockerpm/design react react-dom

Icons are available from the dedicated @lockerpm/design/icons entry point.

Quick start

Import the self-hosted Locker typeface and reset stylesheet once at the application entry point, then wrap the application in LockerAppProvider:

import '@lockerpm/design/font.css';
import '@lockerpm/design/reset.css';

import { Button, LockerAppProvider, Space } from '@lockerpm/design';
import { SafetyCertificateOutlined } from '@lockerpm/design/icons';

export function App() {
  return (
    <LockerAppProvider>
      <Space>
        <Button type="primary" icon={<SafetyCertificateOutlined />}>
          Create secret
        </Button>
        <Button>Cancel</Button>
      </Space>
    </LockerAppProvider>
  );
}

Components and TypeScript types available from Ant Design are re-exported from the package root, so application code can use one consistent UI dependency.

Theming

LockerAppProvider applies the canonical Locker tokens and context-aware feedback APIs by default. Supply a partial Ant Design theme to override product-specific values without losing the Locker baseline:

import { LockerAppProvider, type ThemeConfig } from '@lockerpm/design';

const productTheme: ThemeConfig = {
  token: {
    borderRadius: 4,
  },
  components: {
    Button: {
      controlHeight: 36,
    },
  },
};

export function AppShell({ children }: { children: React.ReactNode }) {
  return <LockerAppProvider theme={productTheme}>{children}</LockerAppProvider>;
}

Use useLockerApp inside the provider for context-aware messages, notifications, and modals:

import { Button, useLockerApp } from '@lockerpm/design';

export function SaveButton() {
  const { message } = useLockerApp();

  return <Button onClick={() => void message.success('Saved')}>Save</Button>;
}

This hook preserves the active theme, locale, and content-security-policy settings. Avoid Ant Design's static global feedback functions in application code.

The package also exports the canonical theme values for advanced integration:

• lockerTheme
• lockerDarkTheme
• mergeLockerTheme
• LOCKER_BRAND_COLORS
• LOCKER_NEUTRAL_COLORS
• LOCKER_SHADOWS
• LOCKER_MOTION
• LOCKER_DESIGN_TOKENS
• LOCKER_COMPONENT_TOKENS

For example, enable the standard dark theme with:

import { LockerAppProvider, lockerDarkTheme } from '@lockerpm/design';

export function DarkApp({ children }: { children: React.ReactNode }) {
  return <LockerAppProvider theme={lockerDarkTheme}>{children}</LockerAppProvider>;
}

Locales

Pass a locale to the provider. Locale modules are available through stable package exports:

import { LockerAppProvider } from '@lockerpm/design';
import viVN from '@lockerpm/design/locale/vi_VN';

export function VietnameseApp({ children }: { children: React.ReactNode }) {
  return <LockerAppProvider locale={viVN}>{children}</LockerAppProvider>;
}

Applications using date or time components must also configure the matching locale for their date library.

Using the theme without the provider

Applications that already own an Ant Design ConfigProvider can apply the Locker theme directly:

import { ConfigProvider, lockerTheme } from '@lockerpm/design';

<ConfigProvider theme={lockerTheme}>{children}</ConfigProvider>;

Use mergeLockerTheme(overrides) when combining the Locker baseline with a product-specific theme.

Migrating from v1 to v2

Version 2 is a major upgrade built on Ant Design 6. Review the Ant Design v6 migration guide alongside these Locker-specific changes:

1. Upgrade React and React DOM to at least 18.2.
2. Install @lockerpm/design@^2 and import components from @lockerpm/design.
3. Replace legacy deep imports such as @lockerpm/design/es/* or @lockerpm/design/lib/* with package-root imports.
4. Replace Less-variable overrides and component stylesheet imports with LockerAppProvider, design tokens, and the optional @lockerpm/design/reset.css entry point.
5. Import locales from @lockerpm/design/locale/<locale>, for example @lockerpm/design/locale/en_US.
6. Replace direct Locker icon imports with @lockerpm/design/icons.
7. Re-run visual, keyboard, and screen-reader regression tests. Ant Design 6 includes DOM, popup, and deprecated-API changes that may require application updates.

Legacy Babel import plugins for per-component stylesheet loading are not required for v2. Modern bundlers can tree-shake the package's ES module entry.

LockerConfigProvider remains available for nested configuration scopes that do not need application-level feedback APIs. LockerDesignProvider is a transition alias for LockerAppProvider.

Security

Security issues should be reported through the Locker Bug Bounty Program. Do not open a public issue for a suspected vulnerability.

License

Locker Design System is available under the MIT License. Ant Design is an MIT-licensed dependency; attribution details are provided in NOTICE.