Protocol: 次世代APIドキュメントサイトのための美しいスターティングポイント

数ヶ月の開発期間を経て、ついに次期ウェブサイトテンプレート「Protocol」をリリースできることを嬉しく思います。これは、素晴らしいAPIリファレンスウェブサイトを構築するための美しいスターターキットです。

Next.jsとMDXを基盤とし、Tailwind CSSでスタイリングされたこのテンプレートは、まさに私たちが自社のAPIリファレンスドキュメントを構築するであろう方法で構築されています。

ライブデモを試すか、Tailwind UIのオールアクセスライセンスをお持ちの場合はソースコードをダウンロードしてください。もちろん、オールアクセスのお客様には無料アップデートとして提供されます。

デザインの細部へのこだわり

いつものように、私たちはデザインに没頭し、サイトの閲覧を本当に楽しいものにするために、細部にまで磨きをかけることに多くの楽しみを感じました。

エンドポイントのリクエストとレスポンスの詳細をスクロールしても、常に表示される固定コードブロックがあります。

ホームページのカードには、美しいホバーエフェクトもあります。マウスカーソルを追尾するグラデーションの光彩が、繊細な背景パターンを浮かび上がらせます。

私のお気に入りのディテールは、サイドバーナビゲーションです。これは、表示されているページコンテンツを追跡しますが、「ミニマップ」戦略のようなものを使用しており、すべての表示されているページセクションがハイライトされます。

ページをスクロールすると、これがアニメーションする様子はまさに圧巻です。ここでもいつものように重労働を担ってくれたFramer Motionに感謝します。たとえReactを心底嫌っていたとしても、このライブラリを使うためだけにReactを使うだろうと確信しています。それほど素晴らしいのです。

私たちが求める開発者体験

私たちは、このテンプレートで実際の内容をどのように組み込むかを決定するために多くの時間を費やしました。さまざまな標準を使用してドキュメントを自動生成するためのさまざまなオプションを検討しましたが、私個人の好みとしては、どれも少し制約があるように感じられました。

個人的には、まさに自分が書きたいドキュメントを自由に書けるようにしたいと思っています。そのため、Protocolでは、最大限のコントロールを可能にしつつ、書きたいことを素早く簡単に書けるように、多くのオーサリングの利便性を最適化しました。

エンドポイントのドキュメントはMDXで記述し、私たちが提供するいくつかの小さなコンポーネントを組み込むことで、構造を素早く構築できます。

messages.mdx

## Create a message {{ tag: 'POST', label: '/v1/messages' }}
<Row>
  <Col>
    Publishes a new message to a specific conversation.
    ### Required attributes
    <Properties>
      <Property name="conversation_id" type="string">
        Unique identifier for the conversation the message belongs to.
      </Property>
      <Property name="message" type="string">
        The message content.
      </Property>
    </Properties>
  </Col>
  <Col sticky>
    <CodeGroup title="Request" tag="POST" label="/v1/messages">
    ```bash {{ title: 'cURL' }}
    curl https://api.protocol.chat/v1/messages \
      -H "Authorization: Bearer {token}" \
      -d conversation_id="xgQQXg3hrtjh7AvZ" \
      -d message="You're what the French call 'les incompetents.'"
    ```
    ```js
    import ApiClient from '@example/protocol-api'
    const client = new ApiClient(token)
    await client.messages.create({
      conversation_id: 'xgQQXg3hrtjh7AvZ',
      message: 'You're what the French call 'les incompetents.'',
    })
    ```
    </CodeGroup>
    ```json {{ title: 'Response' }}
    {
      "id": "gWqY86BMFRiH5o11",
      "conversation_id": "xgQQXg3hrtjh7AvZ",
      "message": "You're what the French call 'les incompetents.'",
      "reactions": [],
      "created_at": 692233200,
    }
    ```
  </Col>
</Row>

これにより、次のようなドキュメントが生成されます。

Example of generated documentation from MDX source

オーサリング体験を本当に素晴らしいものにするために、私たちはmdx-annotationsという新しいライブラリまで構築しました。これは、Markdocを使用していたときに気に入っていたアノテーション機能をMDXにもたらすものです。

これにより、次のような見出しのように、オブジェクトでタグをアノテーションすることで、MDXコンテンツ内のタグにpropsを渡すことができます。

## Create a message { tag: 'POST', label: '/v1/messages' }

...これは、次のようなJSXに変換されます。

<Heading level={2} tag="POST" label="/v1/messages">
  Create a message
</Heading>

これにより、Markdownで書き続けることができ、追加のデータを渡すためだけに生のJSXに切り替える必要がないため、かなり迅速に進めることができます。

順応性の高いデザイン

このテンプレートは、多くの人々にとってすぐに非常に役立つものになると考えているため、ブランドに合わせてデザインを簡単にカスタマイズできるようにすることが重要でした。

私たちは、サイトで使用しているイラスト入りの背景パターンを、基本的に誰にとっても「ブランドに合っている」と感じられるように意図的に設計しました。プロのデザイナーの仕事であることがわかると思いますが、シンプルで「技術的」なモチーフに傾倒しており、これはすべてのAPIリファレンスサイトに共通するものです。

The illustrated background pattern included in this template

パターンを、すべての色が組み込まれたアセットとしてエクスポートするのではなく、コードで構築したため、独自のカラースキームに合わせて簡単に調整できます。

構文ハイライトには、css-variablesテーマのShikiを使用しています。これにより、わずか9色を選択するだけで、ブランドの構文ハイライトを簡単に更新できます。

:root {
  --shiki-color-text: theme("colors.white");
  --shiki-token-constant: theme("colors.emerald.300");
  --shiki-token-string: theme("colors.emerald.300");
  --shiki-token-comment: theme("colors.zinc.500");
  --shiki-token-keyword: theme("colors.sky.300");
  --shiki-token-parameter: theme("colors.pink.300");
  --shiki-token-function: theme("colors.violet.300");
  --shiki-token-string-expression: theme("colors.emerald.300");
  --shiki-token-punctuation: theme("colors.zinc.200");
}

これは、独自のテーマをゼロから作成しようとするよりも、はるかに手間がかかりません！

デモで使用した4つのアイコンに加えて、一般的なAPIリソースタイプのためにさらに24個のアイコンを含めました。

こちらのスクリーンショットをご覧ください。ここでは、Protocolテンプレートを、APIリファレンスを強化するためにConvertKitの友人が使用しているかのように適応させています。

一見すると大きく異なって見えますが、よく調べてみると、実際にはほとんど何も変わっていません。変更したのは、ボタンとリンクの色、ロゴ、イラストのグラデーションの調整、そして異なる構文ハイライトの色を選択しただけです。

ダークモード

当然のことながら、このサイトにはダークモードのサポートが含まれています。開発者向けに作られているのに、私たちがそんなに無知である可能性があると本当に思いますか？あなたは決して私たちを許さないでしょう。

The Protocol template design in dark mode

ダークモードバージョンにも、独自のクールなデザインのディテールがたくさんあります。例えば、プライマリボタンの処理の違いが気に入っています。

Algolia DocSearch統合によるコマンドパレット

私たちはドキュメント検索にAlgoliaを愛用しており、Tailwind CSSのウェブサイトやSyntaxテンプレートでも使用しています。

Protocolにも組み込みましたが、今回はAlgoliaのヘッドレスautocompleteライブラリを使用しているため、検索UIを完全にコントロールできました。

このアプローチの良い点は、すでにスタイルが設定されているウィジェットをスタイリングするためにカスタムCSSを書く代わりに、通常のユーティリティクラスを使用してすべてをスタイリングできることです。これは、Tailwind CSSプロジェクトではるかに正しいと感じられます。

以上が、2022年を締めくくる最後のTailwind UIテンプレートです！もう1つもほぼ準備ができていますので、新年にはそちらもご期待ください。そして、Tailwind CSS v4.0に関する非常にエキサイティングなニュースも近日中に発表する予定です！