optics-context

Optics

Optics は RoleModel の CSS デザインシステムで、@rolemodel/optics として公開されています。インストール済みパッケージが、利用可能なコンポーネントとトークンの正確な情報源です。トークンはバージョンによって変わるため、名前を記憶から呼び起こすのではなく、パッケージを確認してください。

• トークン：node_modules/@rolemodel/optics/dist/tokens/tokens.json（古いバージョンでは dist/css/core/tokens/ 以下の CSS）
• コンポーネント：node_modules/@rolemodel/optics/dist/css/components/*.css
• バージョン：package.json の @rolemodel/optics エントリー
• ドキュメント：https://docs.optics.rolemodel.design

CSS を記述する前に

1. 適合する Optics コンポーネントを使います。 ブロックとそのモディファイアを dist/css/components/ で確認してください。
2. 既存のプロジェクトクラスを再利用します。 app/assets/stylesheets/ を検索してください。
3. どちらも適合しない場合に限り、新しいコンポーネントを作成します。 bem-structure スキルに従って命名・ネストし、app/assets/stylesheets/components/{block}.css にブロックごとにファイルを作成してください。

Optics コンポーネントのアプリ全体での見た目を変更するには、app/assets/stylesheets/components/overrides/{component}.css でオーバーライドします。新しいブロックとしてフォークしないでください。

Optics にはユーティリティクラス（.flex、.gap-sm、および dist/css/core/utilities.css 内のその他のクラス）も含まれています。RoleModel はビューでの使用を強く推奨していません。代わりに、BEM ブロックまたは要素を通じてスタイルを設定してください。

リテラル値ではなくトークンを使う

色、余白、フォント、角丸、境界線、シャドウの値はすべてトークンを使います。

次の代わりに	次を使用
#fff、rgb(...)、white	var(--op-color-background)、var(--op-color-primary-base)
padding: 12px	padding: var(--op-space-small)
border: 1px solid #ddd	border: var(--op-border-width) solid var(--op-color-border)
box-shadow: 0 1px 3px rgba(...)	box-shadow: var(--op-shadow-small)

色付きの面にテキストを配置する場合は、その面に対応する on- トークンを使います。たとえば、--op-color-primary-base には --op-color-primary-on-base を、--op-color-primary-plus-two には --op-color-primary-on-plus-two を使います。

適合するトークンがない場合は、アプリ独自のプレフィックスを付けてプロジェクトトークンを定義します（「Your App」の場合は --ya-color-brand-accent）。--op- 以下に新しい名前を追加しないでください。

注意点

• 名前が不正でもエラーは表示されません。 var(--op_color_primary_base)、var(--color-primary-base)、var(--op-primary-color-base) はすべて何も解決されず、エラーなしでプロパティがフォールバックします。tokens.json で名前を確認してください。
• ダークモードではプラスとマイナスが逆転します。 各ステップは light-dark() のペアです。ライトモードでは plus-* が明るく、minus-* が暗くなります。ダークモードでは逆転するため、plus-max は最も明るいステップから最も暗いステップに変わります。「明るい」か「暗い」かではなく、背景に対する役割でステップを選び、scale_color_tokens.css で両方の値を確認してください。
• Optics には想像以上に多くのコンポーネントがあります。 btn と card のほかに、avatar、badge、tag、alert、modal、table、tab、switch、spinner、sidebar、side-panel、text-pair、segmented-control などが含まれています。ブロックを記述する前に dist/css/components/ を確認し、確認できる場合に「お使いの Optics のバージョンに含まれていれば」といった曖昧な表現をしないでください。Optics と同じ名前で独自ブロック（新しい .avatar { … } など）を記述しても、別のコンポーネントにはなりません。Optics のルールに統合され、アプリ内のすべてのアバターが変わります。Optics のブロックを使い、変更は components/overrides/{component}.css またはプロジェクトのモディファイアに記述してください。
• テーマの一部だけをオーバーライドすると、スケールが崩れます。 --op-color-* の値を変更する前に、references/theming.md を参照してください。

テーマ設定

アプリ全体のブランドカラー、フォント、角丸、またはカラースケールを変更するには、references/theming.md を参照してください。