Document Kryon CSS and run conformance in CI

This commit is contained in:
waozi committed 2026-11-07 13:58:38 -03:00
1 parent 240cf61ab6
commit 89a0a8b174
3 files changed
+134 -54

No files matched your search

+11 -5
View File
@@ -12,7 +12,7 @@ jobs:
steps:
- uses: actions/checkout@v7
with:
path: kss
path: css
- name: Build the ziran launcher
run: |
@@ -21,20 +21,26 @@ jobs:
echo "$PWD/ziran/build/bin" >> "$GITHUB_PATH"
- name: Test
working-directory: kss
working-directory: css
run: |
ziran fetch --locked
make test style-pack-check
# C, C++, Go, ZX and the browser export must agree; Android runs
# where a phone is attached, so it is skipped here.
- name: Conformance
working-directory: css
run: env -u DISPLAY -u WAYLAND_DISPLAY make conformance
# A failure names the seed; rerun it with make fuzz FUZZ_SEED=N.
- name: Fuzz with this run's seed
working-directory: kss
working-directory: css
run: env -u DISPLAY -u WAYLAND_DISPLAY make fuzz FUZZ_SEED=${{ github.run_number }} FUZZ_COUNT=10000
- name: Keep a failing sheet
if: failure()
uses: actions/upload-artifact@v7
with:
name: kss-fuzz-failure
path: kss/build/kss-fuzz/failure-*.kss
name: css-fuzz-failure
path: css/build/css-fuzz/failure-*
if-no-files-found: ignore
+116 -45
View File
@@ -1,63 +1,134 @@
# KSS
# Kryon CSS
KSS is the style sheet language of [Kryon](https://github.com/kryonlabs/kryon)
applications. This package parses and formats `.kss` sheets, resolves their
`@import`s and color tokens, installs the rules into Kryon's style table, and
ships the classic, lightfield, and material style packs in `styles/`. Kryon
itself only resolves installed rules; apps that read `.kss` text add this
package.
Kryon applications are styled with a subset of CSS. This package parses
`.css` sheets into Kryon's style table, compiles style packs into tables apps
load without parsing, formats sheets, exports them to browser CSS for
Kryon's document host, and converts old KSS sheets. It ships the classic,
lightfield and material packs in `styles/`. The same table drives every
Kryon backend: desktop, console, Android, the web canvas and DOM hosts, and
apps built through the C, C++ and Go targets.
## Use it
```sh
ziran add https://github.com/kryonlabs/kss.git
ziran add https://github.com/kryonlabs/css.git
```
```zi
using Styles :: #import "kss/Kss";
#import "kss/SystemStyle"
using Styles :: #import "css/Css";
#import "css/SystemStyle"
sheet: CssSheet;
Start :: () {
if !CssSheetLoad(*sheet, StylePackClassic()) { return }
if CssSheetParse(*sheet, app_css, "app.css", CssNoImports) {
CssSheetInstall(*sheet, CssDefaultEnvironment(), null)
}
}
```
`BeginStyleRules`, `ParseStyleRules`, and `InstallParsedStyleRules` parse a
sheet in steps and install it; `ProvideStyleRulesImport` answers an
`@import`. `SystemStyle` picks a pack that matches the desktop theme. The
classic pack is also compiled in as `style_pack_classic`, so an app can
install it without shipping the `.kss` file.
A sheet is parsed whole or not at all: `CssSheetParse` returns false with a
diagnostic such as `unknown property 'colr' at app.css:2:3`
(`CssSheetDiagnostic`). `CssSheetInstall` resolves `var()` for an
environment and installs the rules and color custom properties together; on
failure the previous style stays. `CssSheetBuild` fills a `StyleRules` table
without installing it, and `CssSheetToken` reads a custom property's value.
`CssOverrideColor` and `CssOverrideLength` let a host override custom
properties (`--accent`, for example) for one install. `SystemStyle`
installs the classic pack with colors that follow the desktop theme.
Customization hosts can use `KssAddTokenOverride` before parsing to override
color, length, duration, or material tokens throughout a pack. A later override
of the same name and kind replaces the earlier value. Names are owned by the
parser; invalid names and exhausted capacity produce diagnostics. Rule
installation validates the new snapshot before replacing existing colors.
Imports go through a resolver you pass: `(name: string) -> CssImportAnswer`.
Hosts without imports pass `CssNoImports`.
## The subset
Selectors are a widget type (`Button`, `TextField`, `App`, `*`), classes
(`.primary`), Kryon attributes (`[role=Label]`, `[tone=Accent]`,
`[emphasis=Soft]`) and one state: `:hover`, `:active`, `:focus`,
`:focus-visible`, `:disabled`, `:selected`, `:checked` or `:loading`, in
comma lists. Combinators and nesting are outside the subset.
Properties: `color`, `background` (a color or a two-stop
`linear-gradient`), `background-color`, `border`, `border-color`,
`border-width`, `border-style` (`solid` or `none`), `border-radius`,
`outline-color`, `opacity`, `padding` (one or two values),
`padding-inline`, `padding-block`, `gap`, `font-size`, `font-family`,
`letter-spacing`, `translate`, `-kryon-material` (`lightfield`, `flat`,
`glass`) and `-kryon-icon-size`. Document layout properties (`width`,
`margin`, `display`, `transition` and the like) are kept for the web
document host and skipped by native hosts.
Values: hex, named, `rgb()`, `rgba()`, `hsl()` and `hsla()` colors; `px`
and `rem` (16px) lengths; `s` and `ms` durations; `var(--name, fallback)`.
`em` and `%` lengths are errors, because Kryon has no inherited font size
or containing block. Custom properties are declared in `:root`.
At-rules: `@import` (before other rules), `@layer` statements and blocks,
`@media` with `prefers-color-scheme`, `prefers-contrast`, `pointer`,
`min-width` and `max-width`, plus Kryon's `-kryon-theme`, `-kryon-density`,
`-kryon-pointer` and `-kryon-platform` features, and `@keyframes`.
`!important`, escapes and `//` comments are errors.
Rules rank by layer (unlayered rules last), then Kryon's specificity, then
source order. Kryon's specificity counts a widget type 1, each attribute 10,
a class 20 and a name 100; states add nothing, because a widget is in one
state at a time (disabled, loading, pressed, hovered, selected, focused, in
that order of precedence).
## Style packs
`styles/NAME.css` is compiled into `src/style_pack_NAME.zi`, a table of
words `CssSheetLoad(*sheet, StylePackNAME())` appends without parsing.
After editing a pack, run `make style-packs` and commit the module with it;
`make style-pack-check` fails when a module no longer matches its CSS or the
CSS is not formatted.
## Formatting
`CssFormat(source, output)` writes one declaration per line with two-space
indentation. It refuses a sheet that does not parse, and checks that the
formatted sheet parses to the same rules. `make format FILES="a.css"` runs
it on files.
## Browser CSS
`ExportCSS(source, path, environment, output)` writes CSS for Kryon's DOM
host. Selectors are scoped under `#kryon-dom-root` and matched against the
`data-kryon-widget`, `data-kryon-class` and ARIA attributes the host
writes; custom properties go on the root, `-kryon-*` declarations are
dropped, environment media queries are decided for `environment`, and
viewport queries stay for the browser. Every selector is wrapped in
`:where()` and rules are written in Kryon's priority order, so the browser
ranks them as native hosts do. Attribute selectors and unresolved imports
are refused with a message, never exported in part. `StyleClass(name)`
returns the class ID Kryon widget props take.
## From KSS
KSS, the earlier style language, is no longer read. `make migrate
IN=old.kss OUT=new.css` converts a sheet, and `CssMigrateKss(source,
output)` converts saved sheets in apps. Tokens become `:root` custom
properties, `@theme` becomes a media query, `foreground` becomes `color`,
`padding-x` and `padding-y` become `padding-inline` and `padding-block`,
`radius` becomes `border-radius`, `:pressed` becomes `:active`,
unitless numbers become `px`, and `[class=x]` becomes `.x`. A construct with
no CSS form, such as `@variant`, is an error naming its line.
## Develop
`ExportCSS(source, path, environment, output)` exports a supplied KSS source
unit to CSS for Kryon's document host. Use the bytes through `result.count`
only when `result.ok` is true. `StyleClass(name)` returns the class ID accepted
by Kryon widget props. The exporter shares the parser, token resolution and
environment rules; widget/class/state selectors become scoped DOM selectors,
numeric units and axis properties are expanded, and media conditions survive.
Source and saved IR run on C, C++ and Go in `tests/css_export_test.sh`.
The C++ host compiles Ziran's generated C output as C++17.
`make check` runs the behavior tests, the conformance test, the style pack
check and the fuzzer. The conformance test (`tests/css_conformance.sh`)
builds each pack with an app sheet over it and requires the same digest of
the rule table and every resolved widget style from the C program, a C++
host, the Go target, a ZX bundle and, when a phone is on adb and the NDK is
installed, an Android build. It then checks the browser export of the app
sheet value by value in headless Chromium. `make fuzz FUZZ_SEED=N
FUZZ_COUNT=M` runs generated and damaged sheets under AddressSanitizer and
UndefinedBehaviorSanitizer; a failing sheet is kept in `build/css-fuzz/`.
The current export subset rejects unresolved imports, KSS layers, nested
selector functions, native materials, unknown foreign blocks and output
overflow. Resolve imports or flatten layers before export. Unsupported output
is reported explicitly rather than producing a usable partial sheet. Browser
CSS keywords and authored units remain literal values. Native-only effects
such as gradient endpoints and materials need an explicit browser stylesheet.
`make check` checks the package, runs the parser and style tests as portable
bundles and native code, verifies that `src/style_pack_classic.zi` matches
`styles/classic.kss`, and fuzzes generated and damaged sheets under
AddressSanitizer and UndefinedBehaviorSanitizer. After editing
`styles/classic.kss`, run `make style-packs` and commit the regenerated
module with it. `make fuzz FUZZ_SEED=N FUZZ_COUNT=M` runs other sheets; a
failing one is kept in `build/kss-fuzz/` with a command that shrinks it.
To test against the local compiler and Kryon checkouts, put this in an
ignored `ziran.local.toml`:
To test against local compiler and Kryon checkouts, put this in an ignored
`ziran.local.toml`:
```toml
[overrides]
+7 -4
View File
@@ -63,11 +63,14 @@ same Go "$OUT/go.txt"
# ZX: the bundle returns the combined digest.
"$ZIRAN" bundle --project --entry css_conformance:CssConformanceAll -o "$OUT/conformance.zx" \
tests/css_conformance.zi 2>&1 | quiet
# The bundle is run by the toolchain that wrote it, the project's own.
ZX_RUN="$ZIRAN"
# The bundle is run by the toolchain that wrote it, the project's own; where
# that is not built, the portable runtime runs the entry from source.
TOOLCHAIN="$("$ZIRAN" pkg path ziran 2> /dev/null)/build/bin/ziran"
if [ -x "$TOOLCHAIN" ]; then ZX_RUN="$TOOLCHAIN"; fi
echo "all $("$ZX_RUN" run "$OUT/conformance.zx")" > "$OUT/zx.txt"
if [ -x "$TOOLCHAIN" ]; then
echo "all $("$TOOLCHAIN" run "$OUT/conformance.zx")" > "$OUT/zx.txt"
else
echo "all $("$ZIRAN" run --entry css_conformance:CssConformanceAll tests/css_conformance.zi 2>&1 | quiet)" > "$OUT/zx.txt"
fi
if ! grep -qx "$(cat "$OUT/zx.txt")" "$EXPECTED"; then
echo "css conformance: ZX printed '$(cat "$OUT/zx.txt")', expected the 'all' line of $EXPECTED" >&2
exit 1