{"_id":"@code-dot-org/component-library","name":"@code-dot-org/component-library","dist-tags":{"latest":"0.1.0-alpha.3"},"versions":{"0.1.0-alpha.3":{"name":"@code-dot-org/component-library","version":"0.1.0-alpha.3","description":"Code.org Design System React components.","keywords":["design-system","code.org"],"homepage":"https://github.com/code-dot-org/code-dot-org/blob/staging/frontend/packages/component-library/#readme","bugs":{"url":"https://github.com/code-dot-org/code-dot-org/issues"},"repository":{"type":"git","url":"git+https://github.com/code-dot-org/code-dot-org.git","directory":"frontend/packages/component-library"},"license":"SEE LICENSE IN LICENSE","sideEffects":["**/*.css"],"exports":{"./package.json":"./package.json","./accordion":{"types":{"import":"./dist/accordion/index.d.ts","require":"./dist/accordion/index.d.ts"},"import":"./dist/accordion/index.mjs","require":"./dist/accordion/index.js"},"./accordion/faqAccordion":{"types":{"import":"./dist/accordion/faqAccordion/index.d.ts","require":"./dist/accordion/faqAccordion/index.d.ts"},"import":"./dist/accordion/faqAccordion/index.mjs","require":"./dist/accordion/faqAccordion/index.js"},"./actionBlock":{"types":{"import":"./dist/actionBlock/index.d.ts","require":"./dist/actionBlock/index.d.ts"},"import":"./dist/actionBlock/index.mjs","require":"./dist/actionBlock/index.js"},"./actionBlock/fullWidthActionBlock":{"types":{"import":"./dist/actionBlock/fullWidthActionBlock/index.d.ts","require":"./dist/actionBlock/fullWidthActionBlock/index.d.ts"},"import":"./dist/actionBlock/fullWidthActionBlock/index.mjs","require":"./dist/actionBlock/fullWidthActionBlock/index.js"},"./alert":{"types":{"import":"./dist/alert/index.d.ts","require":"./dist/alert/index.d.ts"},"import":"./dist/alert/index.mjs","require":"./dist/alert/index.js"},"./breadcrumbs":{"types":{"import":"./dist/breadcrumbs/index.d.ts","require":"./dist/breadcrumbs/index.d.ts"},"import":"./dist/breadcrumbs/index.mjs","require":"./dist/breadcrumbs/index.js"},"./button":{"types":{"import":"./dist/button/index.d.ts","require":"./dist/button/index.d.ts"},"import":"./dist/button/index.mjs","require":"./dist/button/index.js"},"./carousel":{"types":{"import":"./dist/carousel/index.d.ts","require":"./dist/carousel/index.d.ts"},"import":"./dist/carousel/index.mjs","require":"./dist/carousel/index.js"},"./checkbox":{"types":{"import":"./dist/checkbox/index.d.ts","require":"./dist/checkbox/index.d.ts"},"import":"./dist/checkbox/index.mjs","require":"./dist/checkbox/index.js"},"./chips":{"types":{"import":"./dist/chips/index.d.ts","require":"./dist/chips/index.d.ts"},"import":"./dist/chips/index.mjs","require":"./dist/chips/index.js"},"./closeButton":{"types":{"import":"./dist/closeButton/index.d.ts","require":"./dist/closeButton/index.d.ts"},"import":"./dist/closeButton/index.mjs","require":"./dist/closeButton/index.js"},"./common/constants":{"types":{"import":"./dist/common/constants/index.d.ts","require":"./dist/common/constants/index.d.ts"},"import":"./dist/common/constants/index.mjs","require":"./dist/common/constants/index.js"},"./common/contexts":{"types":{"import":"./dist/common/contexts/index.d.ts","require":"./dist/common/contexts/index.d.ts"},"import":"./dist/common/contexts/index.mjs","require":"./dist/common/contexts/index.js"},"./common/helpers":{"types":{"import":"./dist/common/helpers/index.d.ts","require":"./dist/common/helpers/index.d.ts"},"import":"./dist/common/helpers/index.mjs","require":"./dist/common/helpers/index.js"},"./common/hooks":{"types":{"import":"./dist/common/hooks/index.d.ts","require":"./dist/common/hooks/index.d.ts"},"import":"./dist/common/hooks/index.mjs","require":"./dist/common/hooks/index.js"},"./common/types":{"types":{"import":"./dist/common/types/index.d.ts","require":"./dist/common/types/index.d.ts"},"import":"./dist/common/types/index.mjs","require":"./dist/common/types/index.js"},"./dialog":{"types":{"import":"./dist/dialog/index.d.ts","require":"./dist/dialog/index.d.ts"},"import":"./dist/dialog/index.mjs","require":"./dist/dialog/index.js"},"./divider":{"types":{"import":"./dist/divider/index.d.ts","require":"./dist/divider/index.d.ts"},"import":"./dist/divider/index.mjs","require":"./dist/divider/index.js"},"./dropdown":{"types":{"import":"./dist/dropdown/index.d.ts","require":"./dist/dropdown/index.d.ts"},"import":"./dist/dropdown/index.mjs","require":"./dist/dropdown/index.js"},"./dropdown/actionDropdown":{"types":{"import":"./dist/dropdown/actionDropdown/index.d.ts","require":"./dist/dropdown/actionDropdown/index.d.ts"},"import":"./dist/dropdown/actionDropdown/index.mjs","require":"./dist/dropdown/actionDropdown/index.js"},"./dropdown/checkboxDropdown":{"types":{"import":"./dist/dropdown/checkboxDropdown/index.d.ts","require":"./dist/dropdown/checkboxDropdown/index.d.ts"},"import":"./dist/dropdown/checkboxDropdown/index.mjs","require":"./dist/dropdown/checkboxDropdown/index.js"},"./dropdown/iconDropdown":{"types":{"import":"./dist/dropdown/iconDropdown/index.d.ts","require":"./dist/dropdown/iconDropdown/index.d.ts"},"import":"./dist/dropdown/iconDropdown/index.mjs","require":"./dist/dropdown/iconDropdown/index.js"},"./dropdown/simpleDropdown":{"types":{"import":"./dist/dropdown/simpleDropdown/index.d.ts","require":"./dist/dropdown/simpleDropdown/index.d.ts"},"import":"./dist/dropdown/simpleDropdown/index.mjs","require":"./dist/dropdown/simpleDropdown/index.js"},"./fontAwesomeV6Icon":{"types":{"import":"./dist/fontAwesomeV6Icon/index.d.ts","require":"./dist/fontAwesomeV6Icon/index.d.ts"},"import":"./dist/fontAwesomeV6Icon/index.mjs","require":"./dist/fontAwesomeV6Icon/index.js"},"./form":{"types":{"import":"./dist/form/index.d.ts","require":"./dist/form/index.d.ts"},"import":"./dist/form/index.mjs","require":"./dist/form/index.js"},"./formFieldWrapper":{"types":{"import":"./dist/formFieldWrapper/index.d.ts","require":"./dist/formFieldWrapper/index.d.ts"},"import":"./dist/formFieldWrapper/index.mjs","require":"./dist/formFieldWrapper/index.js"},"./footer":{"types":{"import":"./dist/footer/index.d.ts","require":"./dist/footer/index.d.ts"},"import":"./dist/footer/index.mjs","require":"./dist/footer/index.js"},"./header":{"types":{"import":"./dist/header/index.d.ts","require":"./dist/header/index.d.ts"},"import":"./dist/header/index.mjs","require":"./dist/header/index.js"},"./heroBanner":{"types":{"import":"./dist/heroBanner/index.d.ts","require":"./dist/heroBanner/index.d.ts"},"import":"./dist/heroBanner/index.mjs","require":"./dist/heroBanner/index.js"},"./image":{"types":{"import":"./dist/image/index.d.ts","require":"./dist/image/index.d.ts"},"import":"./dist/image/index.mjs","require":"./dist/image/index.js"},"./link":{"types":{"import":"./dist/link/index.d.ts","require":"./dist/link/index.d.ts"},"import":"./dist/link/index.mjs","require":"./dist/link/index.js"},"./list":{"types":{"import":"./dist/list/index.d.ts","require":"./dist/list/index.d.ts"},"import":"./dist/list/index.mjs","require":"./dist/list/index.js"},"./list/simpleList":{"types":{"import":"./dist/list/simpleList/index.d.ts","require":"./dist/list/simpleList/index.d.ts"},"import":"./dist/list/simpleList/index.mjs","require":"./dist/list/simpleList/index.js"},"./modal":{"types":{"import":"./dist/modal/index.d.ts","require":"./dist/modal/index.d.ts"},"import":"./dist/modal/index.mjs","require":"./dist/modal/index.js"},"./notification-banner":{"types":{"import":"./dist/notification-banner/index.d.ts","require":"./dist/notification-banner/index.d.ts"},"import":"./dist/notification-banner/index.mjs","require":"./dist/notification-banner/index.js"},"./popover":{"types":{"import":"./dist/popover/index.d.ts","require":"./dist/popover/index.d.ts"},"import":"./dist/popover/index.mjs","require":"./dist/popover/index.js"},"./radioButton":{"types":{"import":"./dist/radioButton/index.d.ts","require":"./dist/radioButton/index.d.ts"},"import":"./dist/radioButton/index.mjs","require":"./dist/radioButton/index.js"},"./segmentedButtons":{"types":{"import":"./dist/segmentedButtons/index.d.ts","require":"./dist/segmentedButtons/index.d.ts"},"import":"./dist/segmentedButtons/index.mjs","require":"./dist/segmentedButtons/index.js"},"./slider":{"types":{"import":"./dist/slider/index.d.ts","require":"./dist/slider/index.d.ts"},"import":"./dist/slider/index.mjs","require":"./dist/slider/index.js"},"./tabs":{"types":{"import":"./dist/tabs/index.d.ts","require":"./dist/tabs/index.d.ts"},"import":"./dist/tabs/index.mjs","require":"./dist/tabs/index.js"},"./tags":{"types":{"import":"./dist/tags/index.d.ts","require":"./dist/tags/index.d.ts"},"import":"./dist/tags/index.mjs","require":"./dist/tags/index.js"},"./themes":{"types":{"import":"./dist/themes/index.d.ts","require":"./dist/themes/index.d.ts"},"import":"./dist/themes/index.mjs","require":"./dist/themes/index.js"},"./textField":{"types":{"import":"./dist/textField/index.d.ts","require":"./dist/textField/index.d.ts"},"import":"./dist/textField/index.mjs","require":"./dist/textField/index.js"},"./toast":{"types":{"import":"./dist/toast/index.d.ts","require":"./dist/toast/index.d.ts"},"import":"./dist/toast/index.mjs","require":"./dist/toast/index.js"},"./toggle":{"types":{"import":"./dist/toggle/index.d.ts","require":"./dist/toggle/index.d.ts"},"import":"./dist/toggle/index.mjs","require":"./dist/toggle/index.js"},"./tooltip":{"types":{"import":"./dist/tooltip/index.d.ts","require":"./dist/tooltip/index.d.ts"},"import":"./dist/tooltip/index.mjs","require":"./dist/tooltip/index.js"},"./typography":{"types":{"import":"./dist/typography/index.d.ts","require":"./dist/typography/index.d.ts"},"import":"./dist/typography/index.mjs","require":"./dist/typography/index.js"},"./video":{"types":{"import":"./dist/video/index.d.ts","require":"./dist/video/index.d.ts"},"import":"./dist/video/index.mjs","require":"./dist/video/index.js"}},"typesVersions":{"*":{"package.json":["package.json"],"*":["dist/*/index.d.ts"]}},"scripts":{"build":"vite build","clean":"rimraf dist .turbo","codemod:buttons":"TS_NODE_TRANSPILE_ONLY=true npx jscodeshift -t ./codemods/button-to-mui-button.ts --parser=tsx --extensions=js,jsx,ts,tsx --require ts-node/register","dev":"vite build --watch","lint":"eslint .","lint:fix":"eslint --fix .","prepack":"clean-package","postpack":"clean-package restore","prettier":"prettier --check .","prettier:fix":"prettier --write .","release":"release-it --preRelease=alpha","start":"yarn dev","stylelint":"stylelint src/**/*.{css,scss,sass}","stylelint:fix":"yarn run stylelint --fix","test":"vitest --run","typecheck":"tsc -b --noEmit"},"prettier":"@code-dot-org/lint-config/prettier/index.mjs","stylelint":{"extends":"@code-dot-org/lint-config/stylelint/index.mjs"},"dependencies":{"lodash":"^4.17.21","react-player":"^3.4.0","react-schemaorg":"^2.0.0"},"devDependencies":{"@code-dot-org/changelogs":"workspace:*","@code-dot-org/component-library-styles":"workspace:*","@code-dot-org/fonts":"workspace:*","@code-dot-org/lint-config":"workspace:*","@emotion/react":"catalog:","@emotion/styled":"catalog:","@mui/material":"catalog:","@release-it/conventional-changelog":"^10.0.0","@testing-library/dom":"catalog:","@testing-library/jest-dom":"catalog:","@testing-library/react":"catalog:","@types/lodash":"^4","@types/node":"catalog:","@types/react":"catalog:","@types/react-dom":"catalog:","@vitejs/plugin-react":"catalog:","classnames":"catalog:","clean-package":"^2.2.0","esbuild-sass-plugin":"^3.3.1","eslint-plugin-storybook":"^10.1.7","glob":"^11.1.0","globals":"catalog:","identity-obj-proxy":"^3.0.0","jscodeshift":"^0.15.2","jsdom":"catalog:","postcss":"^8.5.23","postcss-modules":"^6.0.1","react":"catalog:","react-dom":"catalog:","release-it":"catalog:","rimraf":"catalog:","schema-dts":"^1.1.5","shadow-dom-testing-library":"^1.13.1","stylelint":"catalog:","swiper":"^11.0.5","ts-node":"^10.9.2","tsc-alias":"^1.8.11","typescript":"catalog:","vite":"catalog:","vite-plugin-dts":"catalog:","vite-plugin-externalize-deps":"catalog:","vite-plugin-lib-inject-css":"catalog:","vitest":"catalog:"},"peerDependencies":{"@emotion/react":"^11.0.0","@emotion/styled":"^11.0.0","@mui/material":"^7.0.0","classnames":"^2.5.1","react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0","swiper":"^11.0.5"},"engines":{"node":">=20"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"clean-package":"./clean-package.config.cjs","_id":"@code-dot-org/component-library@0.1.0-alpha.3","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-TYB1GG40RwV7/6Mul/xz0Ur8zv63Hkcj4N+0i1cqAZ2ik3VcpBsDsN6Y1GBUUaPFpShtFhgX4Zry2sHOFCJQIw==","shasum":"c9772e79193437d8a34e431c5d7bf98ca94dfa90","tarball":"https://registry.npmjs.org/@code-dot-org/component-library/-/component-library-0.1.0-alpha.3.tgz","fileCount":971,"unpackedSize":2009866,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFoGRlZmxGMKo7+QiWqAVqnw33UWGE11s10BFbPiTZEvAiEAwqo2Nk+OZrPcymLOM2b101cU0KbfDLNjm9BpH/X3U2g="}]},"_npmUser":{"name":"stephenliangcodeorg","email":"stephen.liang@code.org"},"directories":{},"maintainers":[{"name":"dev-code-org","email":"site@code.org"},{"name":"hamms","email":"elijahhamovitz@gmail.com"},{"name":"daynew","email":"d@daynewagner.com"},{"name":"jessicakulwik","email":"jessica@code.org"},{"name":"bethanycodeorg","email":"bethany@code.org"},{"name":"breville","email":"brendan@code.org"},{"name":"alice-fisher","email":"alice.fisher@code.org"},{"name":"moenm","email":"molly@code.org"},{"name":"hannah.bergam","email":"hannah.bergam@code.org"},{"name":"sanchit.malhotra126","email":"sanchit@code.org"},{"name":"bpcb","email":"ben@code.org"},{"name":"mgc1194","email":"mario.gil-correa@code.org"},{"name":"mikeharv","email":"mike.harvey@code.org"},{"name":"stephenliangcodeorg","email":"stephen.liang@code.org"},{"name":"snickell","email":"snickell@gmail.com"},{"name":"wilkie","email":"wilkie05@gmail.com"},{"name":"alex-m-rob-cdo","email":"alex.brown@code.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/component-library_0.1.0-alpha.3_1786400652317_0.5776785747072097"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-10T22:24:12.112Z","0.1.0-alpha.3":"2026-08-10T22:24:12.542Z","modified":"2026-08-10T22:24:12.878Z"},"maintainers":[{"name":"dev-code-org","email":"site@code.org"},{"name":"hamms","email":"elijahhamovitz@gmail.com"},{"name":"daynew","email":"d@daynewagner.com"},{"name":"jessicakulwik","email":"jessica@code.org"},{"name":"bethanycodeorg","email":"bethany@code.org"},{"name":"breville","email":"brendan@code.org"},{"name":"alice-fisher","email":"alice.fisher@code.org"},{"name":"moenm","email":"molly@code.org"},{"name":"hannah.bergam","email":"hannah.bergam@code.org"},{"name":"sanchit.malhotra126","email":"sanchit@code.org"},{"name":"bpcb","email":"ben@code.org"},{"name":"mgc1194","email":"mario.gil-correa@code.org"},{"name":"mikeharv","email":"mike.harvey@code.org"},{"name":"stephenliangcodeorg","email":"stephen.liang@code.org"},{"name":"snickell","email":"snickell@gmail.com"},{"name":"wilkie","email":"wilkie05@gmail.com"},{"name":"alex-m-rob-cdo","email":"alex.brown@code.org"}],"description":"Code.org Design System React components.","homepage":"https://github.com/code-dot-org/code-dot-org/blob/staging/frontend/packages/component-library/#readme","keywords":["design-system","code.org"],"repository":{"type":"git","url":"git+https://github.com/code-dot-org/code-dot-org.git","directory":"frontend/packages/component-library"},"bugs":{"url":"https://github.com/code-dot-org/code-dot-org/issues"},"license":"SEE LICENSE IN LICENSE","readme":"# @code-dot-org/component-library\n\nCode.org Design System React component library.\n\nWelcome to the Code.org Design System Component Library! This package contains the design system components used\nacross Code.org's frontend applications to ensure consistency and reusability of UI components.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Development](#development)\n- [Usage](#usage)\n- [API Reference](#api-reference)\n- [Best Practices](#best-practices)\n- [Styling](#styling)\n- [Testing](#testing)\n- [Accessibility](#-accessibility)\n- [Contributing](#contributing)\n- [FAQ / Troubleshooting](#faq--troubleshooting)\n- [Changelog](#changelog)\n\n## Overview\n\nCode.org Design System React component library.\n\nComponent-library provides a collection of reusable components, helpers, hooks, contexts, etc and guidelines to help\nyou build consistent and accessible user interfaces. It aims to improve the development process by offering a unified\ndesign language and reducing the need for redundant code.\n\n🔹 Why this package exists:\n\n- Improve development speed by reducing the need to write custom components.\n- Ensure consistent design across Code.org applications.\n- Maintain accessible and user-friendly components.\n\n🔹 Key Features:\n\n- ✅ Built-in support for theming (light/dark mode) [Currently in progress, only part of the components are themed\n  (those that use @code-dot-org/component-library-styles/colors.css)]\n- ✅ TypeScript support\n- ✅ Accessibility-first design\n- ✅ Well-documented with Storybook ([See Storybook](https://code-dot-org.github.io/code-dot-org/component-library-storybook))\n\n## Installation\n\nInside code-dot-org/code-dot-org, the package is linked, not installed: `apps/` uses `portal:` and\n`frontend/` workspaces use `workspace:*`. Nothing below applies to in-repo consumers.\n\nOutside the repository, install from npm along with its peers and the design tokens. The published\nversions are prereleases (`0.1.0-alpha.x`); pin an exact version if you need a stable target:\n\n```bash\nnpm install @code-dot-org/component-library @code-dot-org/component-library-styles\nnpm install react react-dom @mui/material @emotion/react @emotion/styled classnames swiper\n```\n\nImport the four token stylesheets once, at your application's entry point, before any component\nrenders. Component CSS is injected automatically by each import; the tokens are not, and without them\nevery color and dimension falls back to nothing:\n\n```ts\nimport '@code-dot-org/component-library-styles/primitiveColors.css';\nimport '@code-dot-org/component-library-styles/colors.css';\nimport '@code-dot-org/component-library-styles/fontVariables.css';\nimport '@code-dot-org/component-library-styles/shapeAndSpacingVariables.css';\n```\n\nComponents are exported per subpath — there is no root entrypoint — so import them individually:\n\n```ts\nimport Checkbox from '@code-dot-org/component-library/checkbox';\nimport {CdoTheme} from '@code-dot-org/component-library/themes';\n```\n\nTwo constraints to be aware of:\n\n- **A CSS-aware bundler is required.** Both builds import their stylesheets (the CommonJS build calls\n  `require('./x.css')`), so plain Node, SSR without a CSS pipeline, or a test runner without a CSS\n  transform will fail on those imports. Jest needs a mapping such as `identity-obj-proxy`.\n- **Webfonts are the host's responsibility.** `fontVariables.css` names Geist and Noto Sans but ships\n  no `@font-face` rules; load those fonts yourself or text falls back to the system sans-serif.\n\n## Development\n\nTo run the code in development mode (build + watch):\n\n```bash\nyarn run dev\n```\n\nThis mode also generates the TypeScript declaration files, which generally take upwards of 20 seconds but is necessary\nfor cross-project development. To skip TypeScript declaration generation (for example, when locally developing\ncomponents without the need to cross-reference):\n\n```bash\nyarn run dev:fast\n```\n\n## Usage\n\nHere are some **basic** examples of how to use the component library in your project. Since these examples are basic,\nthey're not showing all the supported props.\n\nFor more examples, check the\n[public Storybook documentation](https://code-dot-org.github.io/code-dot-org/component-library-storybook),\nwhich contains usage examples for all components. You can also explore the component source code and related stories\ndirectly.\n\n### Example with `Checkbox`\n\nUse `Checkbox` for toggling a boolean option:\n\n```jsx\nimport {useState} from 'react';\nimport Checkbox from '@code-dot-org/component-library/checkbox';\n\nconst Example = () => {\n  const [isChecked, setIsChecked] = useState(false);\n\n  return (\n    <Checkbox\n      name=\"terms\"\n      checked={isChecked}\n      onChange={e => setIsChecked(e.target.checked)}\n      label=\"I agree to the terms\"\n    />\n  );\n};\n```\n\n- `checked` — Controlled checked state.\n- `onChange` — Handles the checkbox change event.\n- `label` — Text label displayed next to the checkbox.\n\n> **Note:** Some components like `Button`, `LinkButton`, `Typography`, and `Breadcrumbs` have been migrated to MUI.\n> Use their MUI equivalents from `@mui/material` instead. See [MIGRATION_STATUS.md](MIGRATION_STATUS.md) for details.\n\n### Example with `Alert`\n\nUse Alert to display status messages or feedback to the user:\n\n```jsx\nimport Alert, {alertTypes} from '@code-dot-org/component-library/alert';\nimport styles from './Example.module.scss'; // Custom styles for the alert\n\nconst Example = () => {\n  const [isAlertVisible, setIsAlertVisible] = useState(true);\n\n  const closeAlert = () => {\n    setIsAlertVisible(false);\n  };\n\n  return (\n    isAlertVisible && (\n      <Alert\n        text=\"Some alert text\"\n        type={alertTypes.success} // Success styling\n        className={styles.alert} // Custom class for additional styling\n        onClose={closeAlert}\n      />\n    )\n  );\n};\n```\n\n- `type={alertTypes.success}` — Defines the style of the alert (success, error, warning, info).\n- `onClose` — Callback to handle alert dismissal.\n- `className={styles.alert}` — Custom styles from a module.scss file.\n\n## API Reference\n\nWe use **TypeScript** to define the API of our components. This means that you can view the available props and their\ntypes directly in your code editor.\n\n### 📖 Where to Find Full API Docs:\n\nYou can also explore the complete API reference and usage examples in the\n[public Storybook documentation](https://code-dot-org.github.io/code-dot-org/component-library-storybook).\n\n### 🛠️ Example (from TypeScript Types)\n\nHere’s an example of how the component API is defined using TypeScript:\n\n```ts\nexport interface AlertProps extends HTMLAttributes<HTMLDivElement> {\n  /** Alert text */\n  text: string;\n  /** Alert link */\n  link?: LinkProps;\n  /** Alert icon */\n  icon?: FontAwesomeV6IconProps;\n  /** Show icon */\n  showIcon?: boolean;\n  /** Alert `isImmediateImportance`. Used to toggle between role='alert' and role='status'\n   * By default set to true, which means we'll render role='alert'\n   *\n   * For context - The `alert` role should only be used for information that requires the user's\n   * immediate attention, for example:\n   * - An invalid value was entered into a form field\n   * - The user's login session is about to expire\n   * - The connection to the server was lost so local changes will not be saved.\n   *\n   * `status` should be used for advisory information for the user that is not important enough to be an alert.\n   * */\n  isImmediateImportance?: boolean;\n  /** Alert custom className */\n  type?: AlertType;\n  /** Alert on Close callback */\n  onClose?: () => void;\n  /** Alert close label */\n  closeLabel?: string;\n  /** Alert custom className */\n  className?: string;\n  /** Alert size */\n  size?: ComponentSizeXSToL;\n}\n```\n\n### 💡 Why TypeScript Matters:\n\n- Ensures type safety at compile time\n- ️Provides rich autocomplete in modern IDEs\n- ️Reduces runtime errors by enforcing prop types\n\n### 🔎 How to Explore More:\n\n- Check the component’s source code for full implementation details.\n- If you only have access to the package (dist) in node_modules, check the .d.ts files for detailed type definitions.\n- Use Storybook to see examples with available props and behavior.\n- Use TypeScript’s autocomplete to explore the component’s API directly in your editor.\n\n## Best Practices\n\n- Use Semantic Colors:\n\n  - Use semantic colors from `@code-dot-org/component-library-styles/colors.css` to maintain consistent theming\n    across light and dark modes. This ensures visual consistency and makes it easier to update themes globally.\n\n- Follow Existing Patterns, maintain consistency by following established patterns for:\n\n  - Naming – Keep names descriptive and consistent with other components.\n  - Structure – Organize files in the same way as other components in the library.\n  - Testing – Follow existing test patterns using Jest, RTL and @testing-library/user-event..\n  - Stories – Ensure the component has a Storybook entry with usage examples.\n  - Styles – Use existing mixins and variables from primitiveColors.css and colors.css.\n\n- Follow the Single Responsibility Principle:\n  Each component should do one thing and do it well. This makes components easier to test, maintain, and reuse.\n\n  - Good Example: A Button component handles only rendering and click events.\n  - Bad Example: A Button component that also manages state or business logic.\n\n- Extract Reusable Parts:\n  If a part of a component is used more than once or could be used elsewhere, extract it into a separate component.\n  This keeps components clean and reduces duplication.\n  - Example: If you have a complex Tooltip inside a component and it’s used elsewhere, extract it into a Tooltip\n    component.\n\n## Styling\n\nWe use **SCSS modules** and **class names** for styling. This ensures that component styles are scoped and isolated,\nwhich helps prevent unintended side effects.\n\n### Overwriting Component Styles\n\nSince SCSS modules generate locally scoped class names, to overwrite the styles of a component, you need to ensure that\nthe overriding styles have the highest specificity priority. Follow the cascade and specificity rules to make sures your\ncustom styles will be applied correctly (if hesitant - please read [MDN Specificity Guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity),\n[Importance of CSS Specificity and its best practices](https://blogs.halodoc.io/best-practices-that-we-follow-to-avoid-specificity-issues/)).\n\n**_Always rely on css selector priority, not the order of stylesheets being loaded or classNames being applied._**.\n(Since order of stylesheets load and or classNames being applied can be changed almost randomly [example here](https://codeai.slack.com/archives/C0T0PNTM3/p1710363328926969)).\n\n**_NEVER RELY ON THE ORDER OF STYLESHEETS BEING LOADED AND/OR CLASSNAMES BEING APPLIED._**\n\n#### ✅ Recommended Approaches: Using SCSS Modules\n\n##### You can define custom styles in a SCSS module and apply them using a parent element or directly on the component.\n\n**Example: Overwriting via parent element style**\n\n```scss\n// Example.module.scss\n.parentDiv {\n  h1 {\n    color: #75de30;\n  }\n}\n```\n\n```jsx\nimport styles from './Example.module.scss';\n\nconst Example = () => (\n  <div className={styles.parentDiv}>\n    <Heading1 visualAppearance=\"heading-sm\">Some Heading</Heading1>\n  </div>\n);\n```\n\n**Example: Overwriting via component-specific class**\n\n```scss\n// Example.module.scss\nh1.customHeadingStyle {\n  color: #b2ff39;\n}\n```\n\n```jsx\nimport styles from './Example.module.scss';\n\nconst Example = () => (\n  <Heading1 visualAppearance=\"heading-sm\" className={styles.customHeadingStyle}>\n    Some Heading\n  </Heading1>\n);\n```\n\n##### Use of CSS Variables for Theming\n\nTheming should rely on semantic colors defined in primitiveColors.css and colors.css. This ensures consistent\ncolor application across components and simplifies light/dark mode handling.\nExample:\n\n```scss\n.customHeadingStyle {\n  color: var(--text-neutral-primary);\n}\n```\n\n#### ❌ Not Recommended Approaches:\n\n##### Avoid Inline Styles\n\nInline styles are harder to override and don’t support media queries or pseudo-selectors.\nExample (❌ not recommended):\n\n```jsx\n<Heading1 visualAppearance=\"heading-lg\" style={{color: '#f00'}}>\n  Some Heading\n</Heading1>\n```\n\n##### Avoid Global Styles\n\nUsing global styles inside component styles can cause conflicts and unintended side effects.\nExample (❌ not recommended):\n\n```scss\nh1 {\n  color: #f00; // ❌ This might override other h1 elements unintentionally.\n}\n```\n\n### Best Practices for Styling:\n\n- Rely on SCSS modules for style isolation and specificity.\n- Use semantic colors (`colors.css`) from `@code-dot-org/component-library-styles` package to keep theming consistent.\n- If it's impossible to use semantic colors, use primitive colors (`primitiveColors.css`) from\n  `@code-dot-org/component-library-styles` instead.\n- Use other colors only when you can't use semantic or primitive colors.\n- Prefer class-based styles over inline styles to maintain override flexibility.\n- Follow the cascade and specificity rules (review [MDN Specificity Guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity),\n  [Importance of CSS Specificity and its best practices](https://blogs.halodoc.io/best-practices-that-we-follow-to-avoid-specificity-issues/)).\n- For dark/light mode support, rely on `semantic colors`, `data-theme` attribute and avoid hard-coded colors.\n\n## Testing\n\nWe use Jest, RTL and @testing-library/user-event for unit tests. Each component should have a corresponding test file that covers\nall possible use cases and edge cases. Where RTL is not enough, we use\n[Storybook Play Function](https://storybook.js.org/docs/writing-stories/play-function) for visual tests.\nWe follow [RTL testing approach](https://kentcdodds.com/blog/testing-implementation-details), testing components how\nuser see/interact with them instead of testing implementation details.\nWe also have eyes tests (in `@code-dot-org/design-system-storybook`) that are used for visual regression testing.\nOn top of that, we have linting rules to ensure code quality, of course.\n\nYou can run the tests using the following commands:\n\n1. Run jest unit tests:\n\n   ```bash\n   yarn test\n   ```\n\n2. Run linting:\n\n   ```bash\n   yarn lint\n\n   yarn lint:fix\n\n   yarn prettier:fix\n   ```\n\n## 🧩 Accessibility\n\nWe follow WCAG guidelines to ensure our components are accessible.\nAccessibility improves usability for all users, including those with disabilities.\n\nShort accessibility Checklist:\n\n- ✅ Full keyboard accessibility\n- ✅ Sufficient color contrast ([APCA](http://www.myndex.com/APCA))\n- ✅ Screen reader support\n- ✅ RTL (right-to-left) languages support\n\nComplete Accessibility Checklist is following:\n\n- ✅ A keyboard user can access full functionality of a component (with props required/suggested as needed to make this\n  happen)\n- ✅ A mouse user can access full functionality of a component (with props required/suggested as needed to make this\n  happen)\n- ✅ A voiceover user can access full functionality of a component (with props required/suggested as needed to make this\n  happen)\\*\\*\n- ✅ We have sufficient color contrast according to\n  the [Advanced Perceptual Contrast Algorithm](http://www.myndex.com/APCA) (APCA)\n- ✅ Site renders and behaves as expected for an RTL user\n- ✅ Styling accommodates differently-sized strings for non-English users\n\nWe also use [Storybook Accessibility Addon](https://storybook.js.org/docs/writing-tests/accessibility-testing) to test\ncomponents for most accessibility issues automatically on each build, but it's not a substitute for manual testing\nas it can't check all the possible issues. Also, RTL testing is done manually.\n\n## Contributing\n\nFor information on how to contribute to this package, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\n## FAQ / Troubleshooting\n\nIf you encounter any issue that is not addressed here - feel free to reach out to us via `#ask-design-system`\nslack channel,\ngithub issues or any other means of communication.\n\n- **Why is my component not rendering correctly?**  \n  Make sure that the component is correctly imported and that Storybook compiles without errors.\n\n- **Can I request a new component or an update to existing one?**  \n  Yes! Create a thread in `#ask-design-system` Slack channel or open a GitHub issue.\n\n- **How do I add a new component and/or make an update to an existing component?**  \n  Follow the guidelines in [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n- **How do I add custom styles to a component?**  \n  Use SCSS modules and class names to ensure that styles are scoped and isolated. For more details\n  see [Styling](#styling).\n\n- **How do I test a component?**  \n  Use Jest, RTL and @testing-library/user-event for unit tests. For more details see [Testing](#testing).\n\n## Changelog\n\nYou can find the latest changelog in [CHANGELOG.md](CHANGELOG.md).\n\nThe changelog is updated with each release. Make sure to check it regularly to stay up to date!\n","readmeFilename":"README.md","_rev":"1-b86cae4847eaf2f939a22b87183c6359"}