# Building with Buckeye UX (BUX) > Component reference for this version: https://bux.osu.edu/ai/index.md and https://bux.osu.edu/ai/components/.json BUX is Ohio State's design system: CSS, JS, Twig templates and design tokens for OSU websites. Documentation lives at . Prefer BUX components and tokens over custom markup and CSS; anything custom drifts from the rest of OSU's sites and breaks on BUX upgrades. ## 1. Work out how the project uses BUX Check before installing anything. Look for BUX already being loaded: | Signal | Project type | What to do | | --- | --- | --- | | `web/themes/wcm-osu/wcm_bux/` exists | WCM Drupal site | BUX is provided by the `wcm_bux` theme. Do not install it again. Use the `bux:` components from step 3. | | `osu/bux` in `composer.json` | Drupal with the BUX module | Use `bux:` Twig components. | | `@osu/bux-source` in `package.json` | npm project | Use `node_modules/@osu/bux-source/dist/`. | | `assets.bux.osu.edu` in a `` | Static or CMS site using hosted assets | Use the HTML markup from step 3. | | None of these | New integration | Install with step 2. | Note the installed BUX version (from `package.json`, `composer.lock` or the asset URL) and use documentation for that version. ## 2. Install (only if BUX is not already present) **Static HTML, or any site where a build step is not wanted:** load the hosted assets, pinned to a version. ```html ``` `bux-styles.css` already imports the BUX web fonts and icon font. **npm:** add the OSU registry to `.npmrc`, then install. ```bash echo "@osu:registry=https://code.osu.edu/api/v4/packages/npm/" >> .npmrc npm install @osu/bux-source ``` Import `dist/css/bux-styles.css` and `dist/js/bux.js` through the project's bundler. **Drupal (not WCM):** add the OSU Composer repository, require the package, enable the module. ```json "repositories": [ { "type": "composer", "url": "https://code.osu.edu/api/v4/group/6209/-/packages/composer/packages.json" } ] ``` ```bash composer require osu/bux drush en bux ``` The module attaches global CSS and fonts site-wide and provides each component as a Single Directory Component under the `bux` namespace. ## 3. Find the component and its markup Look up what BUX offers before writing any markup. Sources, in order of preference: 1. **`dist/ai/index.md`** in the installed package (newer versions): every component with its status. Per-component details are in `dist/ai/components/.json`: props, allowed values, required props, slots, deprecations and worked examples. 2. **`dist/html/.html` and `dist/html/--.html`**: rendered markup for every component and variant. Use these for plain HTML and JS framework projects. `dist/html/templates/` has full page layouts (with and without a sidebar). 3. **The Twig template** (`dist/twig/.twig`, or `components//` in the Drupal module): its opening comment lists every prop. Drupal's `.component.yml` has the same as a schema. 4. **** for usage guidance and when to use which component. Only use components with status `ready`. Never use a prop marked deprecated. ### Use the component, by project type **Twig (Drupal or other):** ```twig {{ include('bux:card', { heading_properties: { heading_text: 'Admissions', heading_level: 3 }, card_body: 'Apply to Ohio State.', link_properties: { link_url: '/apply', link_text: 'Start your application' }, modifier: 'horizontal', }, with_context = false) }} ``` Use `{% embed 'bux:' %}` with `{% block %}` only for components that define slots. Outside Drupal, include `dist/twig/.twig` by path instead of `bux:`. **Plain HTML:** copy the markup from `dist/html/`, then change the text and attributes. Keep every class, `role`, `aria-*` attribute and visually hidden element. They are what make the component look right and work for screen readers. **React, Vue, Svelte and similar:** port the `dist/html/` markup into a small wrapper component (`class` becomes `className` in JSX). Keep the class names and ARIA attributes exactly. Components that need JavaScript (accordions, menus, tabs, carousels and similar) get it from `bux.js`, which initializes matching markup on page load and again whenever new markup is added to the page, so load `bux.js` once and do not reimplement those behaviors in the framework. In Drupal it registers as `Drupal.behaviors` instead. ## 4. Layout, spacing and icons - **Page width:** wrap content in `.bux-container`. - **Grid:** `.bux-grid` with `.bux-grid__cell` children; set widths with `.bux-grid__cell--{1-12}` and per breakpoint with `.bux-grid__cell--6@lg`. - **Spacing:** use the utility classes (`.bux-mar-top-sp-32`, `.bux-pad-all-sp-16`, and similar) before writing margin or padding CSS. - **Icons:** ``, with the icon name from the BUX icon library. Give icon-only controls an accessible label. - **OSU pages** normally use the `osu-navbar`, `header` and `footer` components. Start from a layout in `dist/html/templates/` rather than building page chrome by hand. ## 5. Custom CSS: use design tokens When BUX does not cover a style, write CSS that uses BUX's CSS custom properties, never raw values. - **Colors**, chosen by the CSS property being set: - `color` uses `--color-content-*` (for example `--color-content-primary`, `--color-content-link`) - `background` uses `--color-background-*` (for example `--color-background-secondary`) - `border` and `outline` use `--color-border-*` (for example `--color-border-primary`) - **Spacing:** `--spacing-{n}` (for example `--spacing-16`) instead of pixel or rem values. - **Type:** `--typography-font-size-{n}`, `--typography-font-weight-*`, `--typography-font-family-sans`. - Do not hardcode hex values, including Ohio State scarlet; use `--color-content-scarlet` or `--color-background-scarlet`. - Do not use the BUX Sass variables or mixins in new code. They are being removed in BUX 2.0. The full token list is in `dist/css/bux-styles.css` (search for `--color-`). ### Dark mode BUX follows the operating system's color scheme. `` or `` forces one. Using tokens makes custom CSS work in both automatically; hardcoded colors will not. Check custom work in both modes. ### Changing a BUX component - Prefer an existing modifier (see the component's props) over new CSS. - If CSS is still needed, scope it to your own class on a wrapper. Do not restyle `.bux-*` classes globally, and do not invent new `bux-*` class names. - In Drupal, a component can be replaced by copying it into the theme's `components/` folder and adding `replaces: bux:` to its `.component.yml`. Do this only when props, modifiers and slots cannot do the job. ## 6. When BUX does not fit If no BUX component matches what the user asked for, say so and name the closest component. Build the custom piece with BUX tokens and layout classes, and keep it visually consistent with BUX. Do not quietly approximate a design with a component that behaves differently. ## Checklist before finishing - [ ] BUX loaded once, pinned to a version - [ ] Existing components used wherever one fits, with `ready` status and no deprecated props - [ ] No invented `bux-*` classes, no hardcoded colors or spacing in custom CSS - [ ] ARIA attributes and heading levels kept from the BUX markup and correct for the page - [ ] Checked in light and dark mode