# Gloss

The design system for Arbitrary Definitions, a personal umbrella of
self-hosted, single-user tools. Sixteen components and six foundations,
documented by a small Ruby/ERB site (no Jekyll) with hand-maintained CSS and
hand-written content.

**Site:** https://kejadlen.github.io/gloss/

## The idea

Arbitrary Definitions is an umbrella for side projects: self-hosted tools
built for one household or one person, never a SaaS product. Gloss is what
those projects share underneath. Almost every value in it is arbitrary — the
accent is teal because someone liked it, the type scale ratio is 1.20 at the
small end because that looked right, not because it is correct. What makes
it a *system* is not that the choices are correct but that they are written
down once, given names, actually used, and therefore changeable.

See [Rationale](https://kejadlen.github.io/gloss/rationale/)
for the four rules this system's build actually enforces.

This is a small, personal project, so it is built as plainly as it can be:

- `assets/css/tokens.css` is a hand-maintained stylesheet of custom
  properties — a `:root` block, both dark-theme selectors, and a
  `prefers-reduced-motion` override that zeroes every duration token. Edit
  the values directly; there is no compiler in front of it.
- `_sass/` holds the component and site-chrome CSS as plain, already-flat
  files (one per component group). `rake build` concatenates them in a fixed
  order into four bundles — `base.css`, `components.css`, `docs.css`,
  `patterns.css` — so a consumer can load just the design system without this
  site's own chrome. No Sass compiler involved.
- The documentation tables, swatches, and contrast figures are static
  markup, transcribed once from the token values rather than recomputed on
  every build.
- Component demos are plain HTML: a `<figure>` with the live preview and,
  underneath it in a `<details>`, the exact same markup as literal text.
  There is no generator keeping the two in sync — there is only one copy.

No component stylesheet contains a color literal or a duration — every one is a `var(--gl-*)`.

## Requirements

Ruby 4.0 (`.ruby-version` pins 4.0.6) and Bundler.

```console
$ bundle install
$ bundle exec rake          # build
$ bundle exec rake serve    # http://127.0.0.1:4000
```

## Layout

| Path | What it is |
| --- | --- |
| `assets/css/tokens.css` | Every color, type, space, radius, elevation, and motion value in the system, hand-maintained. |
| `_sass/` | Plain CSS: base/reset, components (core/forms/feedback/navigation), and this documentation site's own chrome. Concatenated into `base.css`, `components.css`, `docs.css`, and `patterns.css` at build time. |
| `lib/build.rb` | The whole site builder in one file: a literal list of pages, front matter, ERB, and Kramdown. No collections config, no layout inheritance, no generic includes system — this is one specific site, not a framework. |
| `_layouts/page.erb` | The one page shell (head, header, sidebar, footer). |
| `_foundations/`, `_components/`, `_patterns/` | The documentation pages — static Markdown and HTML with a little ERB for links and nav. |
| `.github/workflows/pages.yml` | Build on Ruby 4.0, deploy to Pages. |

## Deployment

There is no Jekyll to run here — `Rakefile`'s `build` task drives
`lib/build.rb` directly — but the build still
runs on GitHub Actions rather than relying on GitHub's hosted build, mainly
so it runs on the pinned Ruby 4.0 rather than whatever Ruby the Pages runner
ships. `.github/workflows/pages.yml` builds it with `ruby/setup-ruby` and
uploads the result with `actions/deploy-pages`.

Every branch is built; only the repository's default branch deploys.

**One-time setup:** set **Settings → Pages → Build and deployment → Source**
to **GitHub Actions**. The workflow token is not permitted to turn Pages on
by itself, so the `deploy` job fails until this is done — the `build` job
runs regardless.

The site's `BASEURL` is a constant in `lib/build.rb` rather than coming from
`actions/configure-pages`, which keeps the build independent of the Pages
API. Change it there if the site ever moves off a project page.

## Using the CSS elsewhere

Three files, in this order, and almost no JavaScript:

```html
<link rel="stylesheet" href="tokens.css">
<link rel="stylesheet" href="base.css">
<link rel="stylesheet" href="components.css">
```

Retheming means overriding a handful of custom properties after `tokens.css`
loads — no recompile, no fork. See [Using the CSS](https://kejadlen.github.io/gloss/install/).

## Claude Code plugin

This repo is also a Claude Code plugin marketplace — `.claude-plugin/marketplace.json`
and `.claude-plugin/plugin.json` at the root, wrapping the `SKILL.md` also at
the root (the standard [Agent Skills](https://code.claude.com/docs/en/skills)
format). Install it from anywhere:

```console
$ claude
> /plugin marketplace add kejadlen/gloss
> /plugin install gloss@gloss
```

Then invoke `/gloss:design-system` for the exact component
contracts, tokens, and voice guidance to build new interfaces that look like
they came from the same hand as this one.