Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): make Token color prop extensible via module augmentation (#4518)

Cindy Zhang37e2b314d76f
diff --git a/.changeset/token-color-extensible.md b/.changeset/token-color-extensible.md
new file mode 100644
index 0000000000..919a6b1f93
--- /dev/null
+++ b/.changeset/token-color-extensible.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Token: make the `color` prop extensible via module augmentation. `TokenColor` is now derived from a `TokenColorMap` interface, so theme packages can add custom colors (and `astryx theme build` generates the type augmentation), matching Badge and Button.
+@cixzhang
diff --git a/packages/core/src/Token/Token.test.tsx b/packages/core/src/Token/Token.test.tsx
index 9fcbeda60b..f0d3928c8c 100644
--- a/packages/core/src/Token/Token.test.tsx
+++ b/packages/core/src/Token/Token.test.tsx
@@ -13,6 +13,7 @@ import {describe, it, expect, vi} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Token} from './Token';
+import type {TokenColor} from './Token';
describe('Token', () => {
it('renders with label', () => {
@@ -51,6 +52,23 @@ describe('Token', () => {
}
});
+ it('reflects a custom (theme-augmented) color as a class and data attribute', () => {
+ // Themes extend TokenColorMap via module augmentation and supply the
+ // styling through generated theme CSS; the runtime just forwards the
+ // value as the stable class + data-color reflection so the theme
+ // selector can match. Cast simulates a consumer-augmented color.
+ render(
+ <Token
+ label="Brand"
+ color={'brand' as TokenColor}
+ data-testid="token-custom"
+ />,
+ );
+ const token = screen.getByTestId('token-custom');
+ expect(token).toHaveClass('astryx-token', 'brand');
+ expect(token).toHaveAttribute('data-color', 'brand');
+ });
+
it('renders as a span with invisible button when onClick is provided', () => {
const handleClick = vi.fn();
render(
@@ -135,10 +153,7 @@ describe('Token', () => {
it('renders endContent', () => {
render(
- <Token
- label="Token"
- endContent={<span data-testid="end">End</span>}
- />,
+ <Token label="Token" endContent={<span data-testid="end">End</span>} />,
);
expect(screen.getByTestId('end')).toBeInTheDocument();
expect(screen.getByText('End')).toBeInTheDocument();
@@ -241,12 +256,7 @@ describe('Token accessibility', () => {
it('disables both buttons when isDisabled is true', () => {
render(
- <Token
- label="Token"
- onClick={() => {}}
- onRemove={() => {}}
- isDisabled
- />,
+ <Token label="Token" onClick={() => {}} onRemove={() => {}} isDisabled />,
);
const buttons = screen.getAllByRole('button');
for (const button of buttons) {
@@ -355,11 +365,7 @@ describe('Token focus outline', () => {
it('invisible button does not show its own focus outline', async () => {
const user = userEvent.setup();
render(
- <Token
- label="Focusable"
- onClick={() => {}}
- data-testid="focus-token"
- />,
+ <Token label="Focusable" onClick={() => {}} data-testid="focus-token" />,
);
const button = screen.getByRole('button', {name: 'Focusable'});
await user.tab();
diff --git a/packages/core/src/Token/Token.tsx b/packages/core/src/Token/Token.tsx
index bc63ebb891..d99c03f1f1 100644
--- a/packages/core/src/Token/Token.tsx
+++ b/packages/core/src/Token/Token.tsx
@@ -5,7 +5,7 @@
/**
* @file Token.tsx
* @input Uses React, ReactNode, StyleXStyles
- * @output Exports Token component, TokenProps, TokenColor types
+ * @output Exports Token component, TokenProps, TokenColor, TokenColorMap types
* @position Core implementation; consumed by index.ts, tested by Token.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
@@ -41,20 +41,37 @@ import {useTranslator} from '../i18n';
// =============================================================================
/**
- * Available color variants for the token.
+ * Extensible color map for Token.
+ *
+ * Theme packages can add custom colors via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Token' {
+ * interface TokenColorMap {
+ * brand: true;
+ * }
+ * }
+ * ```
+ */
+export interface TokenColorMap {
+ default: true;
+ red: true;
+ orange: true;
+ yellow: true;
+ green: true;
+ teal: true;
+ cyan: true;
+ blue: true;
+ purple: true;
+ pink: true;
+ gray: true;
+}
+
+/**
+ * Token color type derived from TokenColorMap.
+ * Extensible via module augmentation of TokenColorMap.
*/
-export type TokenColor =
- | 'default'
- | 'red'
- | 'orange'
- | 'yellow'
- | 'green'
- | 'teal'
- | 'cyan'
- | 'blue'
- | 'purple'
- | 'pink'
- | 'gray';
+export type TokenColor = keyof TokenColorMap;
export type TokenSize = 'sm' | 'md' | 'lg';
diff --git a/packages/core/src/Token/index.ts b/packages/core/src/Token/index.ts
index f234d02a7a..481fe84716 100644
--- a/packages/core/src/Token/index.ts
+++ b/packages/core/src/Token/index.ts
@@ -12,4 +12,4 @@
*/
export {Token} from './Token';
-export type {TokenProps, TokenColor, TokenSize} from './Token';
+export type {TokenProps, TokenColor, TokenColorMap, TokenSize} from './Token';