`:::pro` ディレクティブの拡張とProコールアウトスタイルの統合

ドキュメント全体に分散していた「Web Awesome Pro」告知用のコールアウトスタイルを utils.css の単一ルールに集約し、:::pro Markdownディレクティブがタイトルとアイコンのオーバーライドをサポートするよう拡張されました。

背景

Proコンポーネント紹介ページやShoelace移行ガイドで使われていたコールアウトのスタイルが、複数箇所に重複して定義されていました。具体的には、migrating-from-shoelace.md にインラインの <style> ブロックと外部スタイルシート (theme-site-embed.css) への <link> タグが存在し、:::pro ディレクティブが生成するコールアウトとは別の視覚スタイルを持っていました。

この状態では、スタイルを変更する際に複数箇所を修正する必要があり、見た目の一貫性も損なわれていました。本PRは wa-callout.pro ルールを utils.css の唯一の正規定義（source of truth）として確立することで、この重複を解消しています。

技術的な変更

utils.css へのスタイル集約

utils.css の wa-callout.pro ルールが拡張され、これまで migrating-from-shoelace.md のインラインスタイルに分散していたプロパティが統合されました。

追加されたスタイルプロパティは以下のとおりです：

• margin-block: calc(var(--wa-content-spacing) * 2) — 前後の余白
• padding: var(--wa-space-l) — 内側の余白
• &::part(icon) に align-items: flex-start — アイコンを上揃えに
• wa-icon[slot='icon'] に font-size: var(--wa-font-size-xl) — アイコンサイズ
• strong に display: block と margin-block-end: var(--wa-space-2xs) — タイトル用ブロック要素
• strong a に color: inherit — タイトル内リンクの色継承

これにより migrating-from-shoelace.md はインライン <style> ブロックと <link rel="stylesheet"> タグの両方を削除でき、ページ固有のスタイル定義がなくなりました。

:::pro ディレクティブの拡張

markdown.js の markdownItContainer 設定が拡張され、:::pro ディレクティブがオプションのタイトルとアイコン指定を受け付けるようになりました。

変更前:

markdown.use(markdownItContainer, 'pro', {
  render: function (tokens, idx) {
    if (tokens[idx].nesting === 1) {
      return `
        <wa-callout class="pro">
          <wa-icon slot="icon" name="star-circle"></wa-icon>
      `;
    }
    return '</wa-callout>\n';
  }
});

変更後:

markdown.use(markdownItContainer, 'pro', {
  validate: params => /^pro(\s+.+)?$/.test(params.trim()),
  render: function (tokens, idx) {
    if (tokens[idx].nesting === 1) {
      const info = tokens[idx].info.trim().replace(/^pro\s*/, '');
      const iconMatch = info.match(/^\{([\w-]+)\}\s*(.*)$/);
      const iconName = iconMatch ? iconMatch[1] : 'hand-wave';
      const title = iconMatch ? iconMatch[2].trim() : info.trim();
      return `
        <wa-callout class="pro">
          <wa-icon slot="icon" name="${markdown.utils.escapeHtml(iconName)}"></wa-icon>
          ${title ? `<strong>${markdown.utils.escapeHtml(title)}</strong>` : ''}
      `;
    }
    return '</wa-callout>\n';
  }
});

新しいディレクティブ構文は以下の3パターンをサポートします：

• :::pro — タイトルなし、デフォルトアイコン (hand-wave)
• :::pro Using Web Awesome Pro? — タイトルあり、デフォルトアイコン
• :::pro {star-circle} Using Web Awesome Pro? — タイトルとアイコンの両方を指定

アイコン名とタイトルテキストはいずれも markdown.utils.escapeHtml() でサニタイズされており、XSS対策が施されています。また、デフォルトアイコンが star-circle から hand-wave に変更されています。

ドキュメントページの更新

docs/index.md と docs/frameworks/react.md の :::pro ディレクティブが新しい構文に更新されました。

変更前:

:::pro
Pro users: get installation instructions from <a href="/workspaces">your&nbsp;workspaces</a> instead.
:::

変更後:

:::pro Using Web Awesome Pro?
Get personalized installation instructions from <a href="/workspaces">your&nbsp;workspaces</a> instead.
:::

タイトルが <strong> タグとしてコールアウトの先頭に表示されるようになり、本文との視覚的な階層が明確になっています。

設計判断

--wa-brand-orange をデザイントークンとして直接参照する方式 が採用され、マーケティング用パレットの外部スタイルシートへの依存が排除されました。

移行前の migrating-from-shoelace.md は --wa-color-brand トークンと theme-site-embed.css に依存していましたが、統合後の utils.css ルールは --wa-brand-orange を直接参照します。これにより、ページごとに外部スタイルシートを読み込む必要がなくなっています。

また、validate 関数の正規表現 /^pro(\s+.+)?$/ により、:::pro の後に任意テキストが続く構文を明示的に許容しています。この検証があることで、markdownItContainer がディレクティブを正しく認識し、追加情報を tokens[idx].info として render 関数に渡せるようになっています。

まとめ

スタイルの重複定義をインライン・外部CSSから utils.css の単一ルールへ集約したことで、Proコールアウトの見た目を変更する際の修正箇所が一か所になりました。:::pro ディレクティブがタイトルとアイコン指定をサポートしたことで、Markdownから直接リッチなコールアウトを記述できるようになり、生HTMLによるマークアップを排除する方向への一歩となっています。