# Install

`@elements/style` is a CSS package. You install it, import it once, and every
page in your app inherits the design system.

## A new app is already wired

`elements create` scaffolds an app with `@elements/style` in place, so you don't
have to add it. The scaffold pins it in `config.jsoc`:

```jsoc
package: {
  dependencies: {
    "@elements/app":   "…",
    "@elements/style": "…",
  },
}
```

and wires the import into `app/shared/styles/page.css`. If you're starting from
a scaffolded app, skip to the Use section below.

## Adding it to an existing app

Install the package:

```bash
elements install @elements/style
```

This resolves the version into `package.lock` (don't edit that file by hand).
The version is pinned in `config.jsoc` under `package.dependencies`. The package
manager keeps it independently versioned from the Elements tooling, so
`@elements/style` follows its own semver.

## Use

One import brings in the whole system with the default monochrome theme:

```css
@import "@elements/style";
```

That single line loads, in order: the scale tokens, the default theme, the
reset, base element styling, typography, and every component and utility. It
also declares the `@layer` order, so importing the root entry handles both the
styles and the cascade architecture at once.

Opt-in extras are separate imports, placed after the root import:

```css
@import "@elements/style";
@import "@elements/style/themes/elements";  /* Elements brand blue */
@import "@elements/style/email";            /* mail-safe email baseline */
```

Note: `@import` statements take no media or supports conditions in the Elements
CSS pipeline. All `@media` logic lives inside file bodies, so plain imports are
all you need.

## Subpath exports

Every module is exported as a subpath, so you can import just what you need
instead of the whole system. Importing the root entry is the common path;
individual subpaths exist for advanced setups.

| Import | What it is |
|---|---|
| `@elements/style` | Everything (default monochrome theme) |
| `@elements/style/tokens/scale` | Non-color scale primitives |
| `@elements/style/themes/default` | Semantic tokens + colors + dark mode |
| `@elements/style/themes/elements` | Elements brand blue (opt-in) |
| `@elements/style/themes/customer-example` | Reference branding recipe |
| `@elements/style/reset` | Minimal reset |
| `@elements/style/base` | Bare-element styling |
| `@elements/style/typography` | Typography helper classes |
| `@elements/style/native` | `progress`, `meter`, `details > summary` |
| `@elements/style/button` | Button family |
| `@elements/style/form` | Form controls and `.field` |
| `@elements/style/layout` | Layout primitives |
| `@elements/style/card` | Card |
| `@elements/style/callout` | Callout |
| `@elements/style/pill` | Pill |
| `@elements/style/tabs` | Tabs |
| `@elements/style/terminal` | Terminal / CLI bar |
| `@elements/style/utilities` | Atomic utilities |
| `@elements/style/email` | Mail-safe email baseline |

Individual component modules assume the token files have loaded first and that
the `@layer` order statement appears before them. Importing the root entry
guarantees both, so if you import subpaths directly, import the tokens (and the
layer declaration) first.

## How a scaffolded app is wired

`elements create` lays down three shared style files under
`app/shared/styles/`, so you have a place for app-wide overrides from day one:

`page.css` is the site-wide page baseline, imported by every page's `style.css`:

```css
@import "./vars.css";
@import "@elements/style";
```

`email.css` is the site-wide email baseline, imported by every email's
`style.css`:

```css
@import "./vars.css";
@import "@elements/style/email";
```

`vars.css` holds your app's token overrides. It's imported by both `page.css`
and `email.css`, so a value you set here applies everywhere. It ships with every
override commented out, so the app is monochrome until you uncomment `--accent`.

A page's own `style.css` imports the shared baseline and then adds page-scoped
rules:

```css
@import "#app/shared/styles/page.css";

.home {
  color: var(--ink);
  background: var(--bg);
}
```

The scaffold ships the **monochrome default**. It does not import
`themes/elements`. Branding is a change to `vars.css` (or a copied theme file);
see [theming](theming) and [overriding](overriding).