Справочник: стили

Ручки сайта: $API/site/$SITE/css и $API/site/$SITE/design. Как работают слои оформления — стили и оформление.

Любая запись CSS или токенов (не dry_run) сбрасывает кэш страниц и сразу собирает заново статические копии страниц сайта — исход в поле ответа rebaked, см. статические копии.

GET /css

Параметр	По умолчанию	Смысл
`include_css`	`1`	`0` — без тела листа
`count`	—	до 20 подстрок через запятую — сколько раз встречается каждая

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/css?include_css=0&count=.site-header,.opdoc__body"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "home_url": "https://test.onpress.pro",
  "option": "onpress_custom_css",
  "exists": true,
  "bytes": 109851,
  "lines": 3130,
  "sha256": "…",
  "autoload": "no",
  "meta": { "updated_at_gmt": "2026-09-24 08:21:04", "updated_by": 1, "bytes": 109851, "sha256": "…", "source": "task-34-accent-tokens", "stripped": [] },
  "blocks": [
    { "name": "FOOTER FRAME (podval-sajta)", "from": 0, "to": 90, "lines": 89, "bytes": 30982 },
    { "name": "HEADER FRAME", "from": 92, "to": 1035, "lines": 942, "bytes": 20260 }
  ],
  "blocks_unclosed": [],
  "outside_bytes": 0,
  "counts": { ".site-header": 127, ".opdoc__body": 210 },
  "css_omitted": "the body was not asked for: repeat without include_css=0 to get it"
}

С телом — css вместо css_omitted. autoload — yes для листов до 64 КБ. blocks — куски между строками-сторожами :root{--имя:1} … :root{--имя-end:1}, from/to — номера строк маркеров с нуля. Старые маркеры-комментарии /* ==== ИМЯ — START ==== */ … END читаются, но записать CSS с ними нельзя — см. ниже.

PUT /css и POST /css

Заменить лист целиком (методы равнозначны).

Поле	По умолчанию	Смысл
`css`	—	весь лист, обязательно; пустая строка допустима
`dry_run`	`false`	вернуть очищенный лист без записи
`flush_cache`	`true`	сбросить весь кэш страниц сайта
`source`	—	метка записи, видна в `meta.source`

curl -s -X PUT "$API/site/$SITE/css" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"css": "body{color:red}</style><script>alert(1)</script>", "dry_run": true}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "option": "onpress_custom_css",
  "bytes": 23,
  "max_bytes": 262144,
  "sha256": "…",
  "autoload": "yes",
  "stripped": [
    { "rule": "style_close_tag", "count": 1, "reason": "закрывающий тег </style> прекращает элемент стилей и пускает остаток как разметку", "samples": ["</style>"] },
    { "rule": "script_tag", "count": 2, "reason": "тег <script> в стилях не нужен; внутри <style> он мёртв, но в любом другом контексте — нет", "samples": ["<script>", "</script>"] }
  ],
  "warnings": [],
  "dry_run": true,
  "applied": false,
  "css": "body{color:red}alert(1)"
}

Настоящая запись отвечает applied: true, updated_at_gmt, cache (status: flushed, empty, skipped, failed; dirs) и rebaked — статические копии. Отказы: 400 css_required, 413 css_too_large (больше 256 КБ; bytes, max_bytes), 422 comments_not_allowed.

CSS сайта уходит в браузер как есть, поэтому комментариев /* … */ и кириллицы вне строк в нём быть не должно — такой CSS отклоняется целиком, проверка идёт и при dry_run. Пропускаются лицензионные заголовки /*! … */ и строки (content: "/* */", адреса в url(…) в кавычках). Блоки размечайте строками-сторожами :root{--имя:1} и :root{--имя-end:1}.

{
  "success": false,
  "error": "comments_not_allowed",
  "message": "site CSS has 1 comment(s) at line(s) 3: code that goes to the browser carries no comments …",
  "kind": "css",
  "count": 1,
  "found": [{ "kind": "block", "line": 3, "text": "/* y */" }]
}

DELETE /css

Удалить лист. Тело необязательно (flush_cache).

{ "success": true, "site_id": "x9HTLHECq", "option": "onpress_custom_css", "cleared": true, "cache": { "status": "flushed" }, "rebaked": { "status": "ok", "total": 1, "baked": 1, "static": { "status": "ok", "pages": [{ "id": 7036, "published": true, "url": "/home-next" }] } } }

GET /design

Параметр	Смысл
`theme`	взять умолчания другой установленной темы

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/design" | jq '{theme, defaults_source, stores, total, changed, css, primary: .tokens["color.primary"]}'

{
  "theme": "onpress-v2",
  "defaults_source": "themes/onpress-v2/assets/css/parts/_variables.css",
  "stores": { "design": "onpress-sidepanel-design", "typography": "onpress-sidepanel-typography", "tokens": "onpress_design_tokens" },
  "total": 66,
  "changed": [],
  "css": "",
  "primary": { "value": "#000000", "default": "#000000", "source": "default", "css_var": "--primary-color", "type": "color", "description": "Primary color" }
}

Каждый токен: value, default, source (default или site), css_var, type (color, px, int, ratio, em, length, string, enum с values, rgb-channels), description. css — то, что тема выводит из третьего хранилища. Список токенов — стили.

PATCH /design

Поле	Смысл
`tokens`	`{имя: значение}`, обязательно (синоним `values`)
`dry_run`	отчёт без записи
`flush_cache`	по умолчанию `true` — сбросить кэш страниц
`theme`	умолчания другой темы

curl -s -X PATCH "$API/site/$SITE/design" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"tokens": {"color.primary": "#0055ff", "h2.size": 40}, "dry_run": true}'

{
  "success": true,
  "dry_run": true,
  "applied": false,
  "site_id": "x9HTLHECq",
  "changed": [
    { "token": "color.primary", "value": "#0055ff", "css_var": "--primary-color", "store": "onpress-sidepanel-design" },
    { "token": "h2.size", "value": 40, "css_var": "--h2-fz", "store": "onpress-sidepanel-typography" },
    { "token": "color.accent", "value": "0 85 255", "css_var": "--primary", "store": "onpress_design_tokens", "derived": true }
  ],
  "css": "html:root{--primary:0 85 255;--primary-light:64 128 255;--primary-dark:0 64 191;}"
}

Настоящая запись — applied: true, stores, cache, rebaked. Отказы: 400 nothing_to_update (нет tokens), 400 unknown_token (token), 400 bad_token_value (token), 400 invalid_theme.

DELETE /design

Поле	Смысл
`tokens`	массив имён (синоним `keys`); без него — сбросить всё
`flush_cache`	по умолчанию `true`

{ "success": true, "site_id": "x9HTLHECq", "reset": ["radius.default"], "css": "", "cache": { "status": "empty", "dirs": ["…/supercache/test.onpress.pro"] }, "rebaked": { "status": "ok", "total": 1, "baked": 1, "static": { "status": "ok", "pages": [{ "id": 7036, "published": true, "url": "/home-next" }] } } }

Без tokens ответ перечисляет в removed_options удалённые хранилища (сайт возвращается к теме целиком).

Статические копии

Страница, которую сайт отдаёт готовым файлом, держит ссылку на файл CSS сайта (его имя меняется вместе с содержимым) и значения токенов на момент сборки, а сброс кэша страниц её не касается. Поэтому PUT, POST и DELETE /css, PATCH и DELETE /design после записи собирают заново все такие копии сайта, и новый CSS виден на них сразу, без POST /frames/rebake. Проверка без записи (dry_run) копий не трогает. Сборка — следствие уже состоявшейся записи: её неудача не отменяет запись и не меняет код ответа, только поле rebaked.

Поле `rebaked`	Смысл
`status`	`ok` — все копии собраны; `partial` — часть не собралась; `failed` — ни одна; `nothing` — копий у сайта нет (`reason`)
`total`	сколько копий у сайта
`baked`	сколько собрано и лежит на месте
`skipped`, `cap`	копий больше предела за один вызов (200): сколько осталось, предел
`static.pages[]`	по странице: `id`, `published`, `url`, `reason` — почему копии нет (например, `renders_on_request`: страница теперь собирается на запросе, копия снята)
`failures[]`	пачки страниц, которые не собрались: `pages`, `status`, `reason`

{ "status": "ok", "total": 1, "baked": 1, "static": { "status": "ok", "pages": [{ "id": 7036, "published": true, "url": "/home-next" }] } }

Сборка идёт пачками по 8 страниц, каждая копия снимается с ответа страницы, поэтому запись на сайте с десятками копий отвечает за несколько секунд.