Surface
Surface
Color, content color, shape, and elevation stay theme-backed.
Tonal elevation (color="surface")
Color roles
Shapes
Shadow elevation
Landmark elements (as)
import type { CSSProperties } from 'react'
import { Surface } from '@language-lit/material3-expressive'
const surfaceColors = [
'surface',
'surface-dim',
'surface-bright',
'surface-container-lowest',
'surface-container',
'surface-container-high',
'surface-container-highest',
'primary',
'primary-fixed',
'primary-fixed-dim',
'secondary',
'secondary-container',
'secondary-fixed',
'secondary-fixed-dim',
'tertiary',
'tertiary-container',
'tertiary-fixed',
'tertiary-fixed-dim',
'error',
'error-container',
'inverse-surface',
] as const
const surfaceShapes = [
'none',
'extra-small',
'extra-small-top',
'small',
'medium',
'large-start',
'large-end',
'large-top',
'large-increased',
'extra-large-top',
'extra-large-increased',
'extra-extra-large',
'full',
] as const
const shadowElevations = [0, 1, 2, 3, 4, 5] as const
const tonalElevations = [1, 2, 3, 4, 5] as const
const surfaceElements = ['article', 'aside', 'header', 'footer', 'nav', 'main'] as const
const swatchGridStyle: CSSProperties = {
display: 'grid',
gap: '0.75rem',
gridTemplateColumns: 'repeat(auto-fill, minmax(9rem, 1fr))',
}
const swatchStyle: CSSProperties = {
display: 'grid',
gap: '0.25rem',
fontSize: '0.75rem',
padding: '0.75rem',
}
export function SurfaceExample() {
return (
<Surface
as="section"
aria-labelledby="surface-example-title"
color="surface-container-low"
shape="extra-large"
className="surface-example"
>
<h2 id="surface-example-title">Surface</h2>
<p>Color, content color, shape, and elevation stay theme-backed.</p>
<Surface
color="primary-container"
shape="large"
shadowElevation={1}
className="surface-example__nested"
>
Nested semantic content
</Surface>
<h3>Tonal elevation (color="surface")</h3>
<div style={swatchGridStyle}>
<Surface color="surface" shape="small" style={swatchStyle}>
Tonal 0 (default)
</Surface>
{tonalElevations.map((level) => (
<Surface key={level} color="surface" tonalElevation={level} shape="small" style={swatchStyle}>
Tonal {level}
</Surface>
))}
</div>
<h3>Color roles</h3>
<div style={swatchGridStyle}>
{surfaceColors.map((color) => (
<Surface key={color} color={color} shape="small" style={swatchStyle}>
{color}
</Surface>
))}
</div>
<h3>Shapes</h3>
<div style={swatchGridStyle}>
{surfaceShapes.map((shape) => (
<Surface key={shape} color="surface-container" shape={shape} style={swatchStyle}>
{shape}
</Surface>
))}
</div>
<h3>Shadow elevation</h3>
<div style={swatchGridStyle}>
{shadowElevations.map((level) => (
<Surface
key={level}
color="surface-container-low"
shadowElevation={level}
shape="small"
style={swatchStyle}
>
Shadow {level}
</Surface>
))}
</div>
<h3>Landmark elements (as)</h3>
<div style={swatchGridStyle}>
{surfaceElements.map((element) => (
<Surface key={element} as={element} color="surface-container" shape="small" style={swatchStyle}>
{`<${element}>`}
</Surface>
))}
</div>
</Surface>
)
}Surfaceは受動的なMaterialコンテナーの基盤です。セマンティックなコンテナー色とコンテンツ色の組み合わせ、シェイプによるクリッピング、色調エレベーション、影のエレベーションを適用しますが、操作動作は追加しません。
import { Surface } from '@language-lit/material3-expressive'
import '@language-lit/material3-expressive/styles.css'
<Surface
as="section"
aria-labelledby="account-heading"
color="surface-container-low"
shape="extra-large"
shadowElevation={1}
>
<h2 id="account-heading">Account</h2>
<p>Profile and security settings.</p>
</Surface>仕様
asの既定値はdivです。div、section、article、aside、main、header、footer、navのみ指定できます。意味は選択した要素が決め、Surfaceはroleを追加しません。colorの既定値はsurfaceです。Surfaceコンテナー系ロールはonSurfaceを使います。アクセント、エラー、固定色、反転色のロールでは、対応するMaterialコンテンツロールを選びます。shapeの既定値はnoneで、現在のシステムの角丸ロールをすべて指定できます。RTLでは開始側と終了側のシェイプが入れ替わります。tonalElevationとshadowElevationは、それぞれ独立して0から5まで指定できます。色調エレベーションが影響するのは基本のsurfaceロールのみです。影のエレベーションは視覚効果であり、CSSの重なり順は変えません。影響を受けない色ロールに0以外の色調レベルを組み合わせると、開発ビルドで警告します。- ネイティブ属性、ARIA/data属性、スタイル、クラス、イベントハンドラー、子要素、および選択した要素に適した型のrefを渡せます。
Surfaceは意図的に非対話型です。クリック、キーボード、無効、選択、チェックの動作には、用途に合ったButton、Card、選択コンポーネントを使ってください。受動的なコンテナーにクリックハンドラーを付けても、キーボード操作には対応しません。
カラーロール
対応するロールは、surface系(surface、surface-dim、surface-bright、5種類のsurface-container-*強度)、primary/secondary/tertiaryの基本・コンテナー・固定ロール、error、error-container、inverse-surfaceです。固定・減光ロールは対応する高強調度のon*Fixedコンテンツ色を使います。低強調度のコンテンツ色は子孫要素で独自に指定できます。
トークン
既定のコンポーネント変数は次のとおりです。
--m3e-comp-surface-container-color--m3e-comp-surface-content-color--m3e-comp-surface-container-shape--m3e-comp-surface-container-shadow--m3e-comp-surface-tonal-overlay-opacity
明示的なバリアントは--m3e-sys-color-*、--m3e-sys-shape-corner-*、--m3e-sys-elevation-*で解決されます。デザインシステム全体を統一するにはシステムテーマを上書きします。未設定のSurfaceの既定値だけを変更する場合に限り、登録済みのSurfaceコンポーネントトークンを上書きしてください。
アクセシビリティと適応
Surfaceはフォーカス対象、キーボード動作、アクセシブルな状態、対話型ロールを追加しません。ランドマーク名や文書アウトラインの正しさはページの文脈に左右されるため、利用側が管理します。モーションはなく、ブラウザーの強制カラー調整も無効化しません。
Webでは、作成したCSSで子要素をクリップし、影を表現します。Android Composeとは異なり、入れ子の実行時CompositionLocalを使って段階的に色調を重ねません。入れ子のSurfaceでは明示的なsurface-containerロールまたは色調レベルを選んでください。これによりスタイルが静的になり、SSRに対応し、スコープ化されたCSSテーマ上書きも反映できます。