# Using the shared design-system artifacts

The downloadable `design.md` and `llms.txt` are the original Russian specifications.
`tokens.css` is their mechanical CSS representation. This English guide explains how
to use them without maintaining a second, potentially drifting set of token values.
These files are a design layer, not a complete standalone application.

## File roles

- `design.md`: the visual intent, color roles, typography, spacing, shape scales,
  component specifications and layout decisions. Change decisions here first.
- `llms.txt`: constraints for the coding agent and the concrete grep commands used
  to check them. It is an instruction file, not an automatic access-control system.
- `tokens.css`: the values used by components. Keep it synchronized with design.md.

## Adaptation sequence

1. Recalculate the reference palette's contrast for your backgrounds, text sizes
   and content. Do not assume a palette suitable for a SaaS screenshot works for
   long-form reading.
2. Choose font families with the glyph coverage you need. This project uses
   Unbounded for display text, Inter for body text and JetBrains Mono for code.
3. Update the specification, then transfer the values to CSS variables once.
4. Keep `@theme static` when Tailwind must emit tokens referenced from scoped styles
   rather than from utility classes. Avoid self-referencing variable definitions.
5. Select a concept before implementing the layout. Record why alternatives were
   rejected so that a future agent does not repeat the same exploration blindly.
6. Use the existing component specifications and token references rather than
   inventing per-component colors and sizes.
7. Run the provided checks in your own source tree and inspect the rendered page
   at narrow and wide widths. Empty grep output is only evidence for the patterns
   searched, not proof of visual correctness.

## Main choices in this blog

The theme is dark-only. Iris is the navigation/focus accent; ember marks artifacts
and author callouts. Body text uses the body-size token and is not reduced on phones.
Code blocks preserve whitespace and scroll internally; long prose identifiers and
table cells can wrap. The article grid must shrink within the viewport rather than
expanding to the longest code line.

RU and EN pages share the same approved layouts and components. Their text, labels
and metadata differ; their design tokens do not. A translation is not a second theme.
For this blog, every published article must have a unique, reciprocal published
partner in the other language; a draft cannot serve as that partner.

Use the original files for exact values and executable checks. If you change a value,
update the specification and stylesheet together rather than editing only the component
that happened to expose the problem.