Applied Form engine

適用形式による標準

実際のブラウザーで測定する、デザインシステム準拠のゲートです。DTCG トークンファイルとページを渡すと、Chromium でページを固定の 4 つの幅とサンプリングした 2 つの幅で、動きを減らす設定と印刷時にレンダリングし、計算済みの値をすべてシステムのルールと照合します。スタイルシートに書かれている内容ではなく、ブラウザーが描画した内容を報告します。

Standards はオープンソースで、根拠を検証できます。Standards を引用する比較はすべて、このリポジトリから再実行できます。axe-core および stylelint と並べたゲート、公開されているデザインシステムの差異調査、モデルの調査とその評価ラウンド、そしてそれらの採点に用いたすべての記録です。

はじめに

npm install @appliedform/standards && npx playwright install chromium
npx standards init --pack instrument  # load a system: the free Standards pack, or your pack's tokens.json
npx standards lint page.html          # your page, judged by that system's rules, at every width

システムが読み込まれていない場合、standards lint は、どのページにも適用されるルール（コントラスト、フォーカス、ターゲットサイズ、オーバーフロー、代替テキスト、見出しの順序、動き）に基づいてページを判定し、システムの読み込み方法を案内します。エージェント向けには、npx standards mcp-config を実行すると、Claude Code または Cursor 用のサーバーブロックが出力されます。

使い方

npx standards lint page.html https://example.com/page      # every rule, every width
npx standards lint https://example.com/ --register ii      # a page that has not declared a register
npx standards baseline https://example.com/a --out standards-baseline.json
npx standards lint https://example.com/a --baseline standards-baseline.json
npx standards fix page.html                                # apply the fixes it can make; writes page.fixed.html
npx standards audit pages/ --fix                           # every page in a folder, as found and as the fixer would leave it, as one report
npx standards drift https://example.com/ --out drift.json  # what system a site actually renders
npx standards rules                                        # every rule, its severity and what it checks
npx standards mcp                                          # the same tools for a model, over MCP

standards fix は、修正後のページがチェック対象のすべてのルールに合格すると終了コード 0 を返し、違反が残ると 1 を返します。また、修正できなかった内容をルール別、要素別に一覧表示します。standards audit は、ルール別およびページ別の検出結果、各ルールが関連する WCAG 基準、チェック対象外の内容、実行を再現するコマンドを含む、単独で完結した HTML ページ（および --json）を書き出します。standards lint は、ベースラインに記録されていないエラー重大度の違反がある場合、終了コード 1 を返します。standards.config.json では、ルールを error、warn、off に設定できます。standards.config.example.json は設定のひな形です。ただし、必須ルールは例外です。トークンファイルの $extensions["form.applied"].levels.mandatory に列挙されている contrast、text-too-small、target-size、focus-hidden、link-not-underlined、alt-missing、horizontal-overflow、wordmark-live-text が該当します。これらのいずれかを warn または off に設定する構成は拒否され、standards lint は終了コード 2 を返します（Applied Form リポジトリの決定 0027）。トークンファイルに読み込み済みシステムがある場合、そのシステムは閾値 contrast と text-too-small（floors.body-contrast、display-contrast、large-text-px、large-bold-text-px、text-min-px）を引き上げることができます。いずれかの閾値をトークンファイル自体の値より下げる場合は拒否されます。パックを宣言しているのに register.pack が指定されていないシステムも拒否されます。その場合、すべてのページを register だけで判定した後に、その独自ルールが破棄されるため、必須ルールが測定されません。レジスターの背景が色ではないシステムも同様です。既知の未対応事項が 4 つあります。読み込んだシステムがレジスターを定義していないページでは、システムの有無にかかわらず、register を引き下げる構成を使うと、必須ルールが測定されません。パックであることを宣言するシステムファイルは、text-too-small、link-not-underlined、wordmark-live-text を対象外として判定されます。地色を描画しないページでは、contrast はシステムが指定する地色を基準に測定します。MCP ツール standards_lint と standards_fix は、呼び出し元が指定した幅だけを測定するため、320 を指定しない呼び出しでは、320px における horizontal-overflow は測定されません。

変更された名前

3.x では、この製品は engine、そのコマンドは af という名前でした。古い名前も 4.x では引き続き動作し、それぞれ stderr に非推奨であることを一度だけ出力します。これらは Standards 5.0.0 で削除されます。@appliedform/standards をインストールする前に、@appliedform/engine をアンインストールしてください。どちらにも af と af-mcp の実行ファイルが含まれているため、一方をもう一方の上にグローバルインストールすると EEXIST エラーになります。

3.x	現在	古い名前
パッケージ @appliedform/engine	@appliedform/standards	先に @appliedform/engine をアンインストールしてください
コマンド af	standards	stderr に 1 行出力してから、同じコマンドを実行します
af-mcp、af mcp	standards mcp	以前と同様に、af_* ツールを一覧表示します
ツール af_lint とその他 8 つ	standards_lint とその他 8 つ	すべてのルートで、どちらの名前も使用できます
af.config.json	standards.config.json	読み込みます。1 行出力し、両方ある場合は新しいファイルが優先されます
af-baseline.json	standards-baseline.json	固有のパスから読み書きし、1 行出力します
.af/	.standards/	設定内で指定されているパスは通常のパスとして扱われ、引き続き動作します
AF_BRAND、AF_CHROMIUM	STANDARDS_SYSTEM、STANDARDS_CHROMIUM	使用するたびに読み込み、1 行出力します。同じ組の両方の名前に異なる値が設定されている場合は、終了コード 2 で終了します
af-audit.html、デフォルトのレポートファイル	standards-audit.html	なし
engine 実行ファイル	なし	なし

意思決定記録や評価プロトコルとその結果など、名前の変更前に記録されたドキュメントでは古い名前が使われており、書き換えられていません。

トークンファイル

tokens/applied-form.tokens.json はリファレンスシステムです。standards brand で生成した中立的なパレットと、Standards の構造（レジスター、ボイス、間隔、フロア、各ルールのパラメーター）が含まれています。これは Standards のテストと公開のために存在します。製品として提供するデザインではありません。ファイルを置き換えるか、standards system import で Standards パックをインポートして、独自のシステムを指定してください。

エビデンス

内容	場所	再実行
意図的に埋め込んだ欠陥を使った、axe-core および stylelint と並ぶゲートの評価	eval/compare.mjs、test/compare.test.mjs	npm run eval:compare
公開デザインシステム間のドリフト	eval/drift/	npm run drift:batch -- all
ルールあり・なしでページを生成するモデル	eval/、docs/evaluation-protocol.md	オフラインでは npm run eval -- --models stub を実行し、その後キーを設定して実行
アンカーと注意確認を含む評価ラウンド	eval/judge-run.mjs	npm run eval:judge

このプロトコルは、それが定める実行より前に作成されており、どのような結果が Standards に不利な評価となるかを明記しています。これらは、このリポジトリのクローンから実行します。npm パッケージに含まれるのは Standards のみで、モデル SDK、axe-core、stylelint を必要とするものは含まれていません。

開発

npm install
npm run check    # build, unit tests, and the clean fixture linted in a real browser

テストには node:test を使用します。Playwright が Chromium をダウンロードしていない場合は、STANDARDS_CHROMIUM に Chromium の実行ファイルを指定してください。

ライセンス

Apache-2.0。LICENSE と NOTICE を参照してください。Applied Form という名称とそのマークはライセンス対象ではありません。