docs: add comprehensive documentation for operations

This commit introduces a complete set of documentation files
covering various aspects of the project, including environment
setup, quality checks, command references, and architecture.
The documentation is structured to assist developers and
contributors in understanding the project's configuration,
workflow, and best practices.

Additionally, translations for Simplified and Traditional
Chinese have been added to ensure accessibility for a wider
audience. This enhances the overall usability and
maintainability of the project.

Signed-off-by: Bertrand Yuan <github@bertyuan.com>

5 files changed, 242 insertions, 0 deletions

diff --git a/Documentation/source/frontend/accessibility.rst b/Documentation/source/frontend/accessibility.rst
new file mode 100644
index 0000000..bca6fbf
--- /dev/null
+++ b/Documentation/source/frontend/accessibility.rst
@@ -0,0 +1,48 @@
+Accessibility
+=============
+
+Baseline
+--------
+
+The current frontend already uses semantic landmarks such as ``main``,
+``section``, and ``article`` in key routes. Several icon buttons include
+accessible labels, and theme-aware colors are centralized through design
+tokens.
+
+Required Practices
+------------------
+
+* Give icon-only controls an accessible name.
+* Preserve visible keyboard focus for custom controls.
+* Keep text readable in both light and dark themes.
+* Use semantic elements before ARIA.
+* Do not hide essential navigation or status only behind animation.
+* Validate empty, loading, success, and error states for forms.
+
+Review Checklist
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 42
+
+   * - Check
+     - Expected Result
+   * - Keyboard navigation
+     - Header, menus, buttons, form controls, and links are reachable.
+   * - Screen reader labels
+     - Icon-only actions have clear names.
+   * - Contrast
+     - Text and UI states remain readable in light and dark modes.
+   * - Layout
+     - Text does not overlap or overflow at mobile and desktop breakpoints.
+   * - Feedback
+     - Form errors and success states are visible and announced where needed.
+
+Known Follow-ups
+----------------
+
+* Improve visible focus states for all custom controls.
+* Audit icon-only social and action links.
+* Add reusable empty states for posts and tags.
+* Add visual regression coverage for critical routes.
diff --git a/Documentation/source/frontend/components.rst b/Documentation/source/frontend/components.rst
new file mode 100644
index 0000000..fc6fa58
--- /dev/null
+++ b/Documentation/source/frontend/components.rst
@@ -0,0 +1,52 @@
+Components
+==========
+
+Component Groups
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 26 52
+
+   * - Area
+     - Files
+   * - Layout
+     - ``src/components/section.tsx``, ``src/components/sections``
+   * - Navigation
+     - ``src/components/active-link.tsx``, header menu and navbar files
+   * - Posts and tags
+     - ``src/components/posts/post-card.tsx``, ``src/components/tags``
+   * - Forms
+     - ``src/components/newsletter-form.tsx``, ``src/components/ui/form.tsx``
+   * - Auth
+     - ``src/components/auth/user-button.tsx``, ``user-avatar.tsx``
+   * - Rich text
+     - ``src/components/rich-text``
+   * - Base UI
+     - ``src/components/ui``
+
+Component Rules
+---------------
+
+Use existing primitives first
+   Before creating a new component, check ``src/components/ui`` and existing
+   page components for a matching pattern.
+
+Keep data access out of presentational components
+   Shared components should receive normalized props. Server components and
+   ``src/lib`` helpers should handle data fetching.
+
+Preserve accessibility names
+   Icon-only buttons and links need explicit labels. Existing tests cover some
+   components; extend tests when adding new interactive behavior.
+
+Keep variants local and typed
+   Use existing ``class-variance-authority`` patterns for variant-heavy
+   controls instead of ad hoc class switches.
+
+Testing
+-------
+
+Component tests live beside components using ``*.test.tsx`` or ``*.test.ts``.
+Prefer focused tests that assert user-visible behavior, accessibility labels,
+and variant output instead of implementation details.
diff --git a/Documentation/source/frontend/index.rst b/Documentation/source/frontend/index.rst
new file mode 100644
index 0000000..d293dca
--- /dev/null
+++ b/Documentation/source/frontend/index.rst
@@ -0,0 +1,13 @@
+Frontend
+========
+
+This section describes page responsibilities, UI conventions, component usage,
+and accessibility expectations for the public site.
+
+.. toctree::
+   :maxdepth: 2
+
+   routes
+   ui-guidelines
+   components
+   accessibility
diff --git a/Documentation/source/frontend/routes.rst b/Documentation/source/frontend/routes.rst
new file mode 100644
index 0000000..ed2c618
--- /dev/null
+++ b/Documentation/source/frontend/routes.rst
@@ -0,0 +1,66 @@
+Routes and Page Responsibilities
+================================
+
+Public Routes
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - Route
+     - Main File
+     - Responsibility
+   * - ``/``
+     - ``src/app/(main)/(home)/page.tsx``
+     - Home page with hero, recent posts, and newsletter CTA.
+   * - ``/posts``
+     - ``src/app/(main)/(home)/posts/page.tsx``
+     - Paginated list of published posts.
+   * - ``/posts/[slug]``
+     - ``src/app/(main)/(home)/posts/[slug]/page.tsx``
+     - Post detail page with rich text, metadata, sharing, and comments.
+   * - ``/tags``
+     - ``src/app/(main)/(home)/tags/page.tsx``
+     - Tag index with post counts.
+   * - ``/tags/[tag]``
+     - ``src/app/(main)/(home)/tags/[...slug]/page.tsx``
+     - Tag-filtered post list.
+   * - ``/about``
+     - ``src/app/(main)/(home)/(mdx)/about/page.mdx``
+     - MDX profile page.
+   * - ``/login``
+     - ``src/app/(main)/(auth)/login/page.tsx``
+     - OAuth login entry.
+   * - ``/admin``
+     - ``src/app/(payload)/admin``
+     - Payload CMS admin.
+
+API and Generated Routes
+------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 56
+
+   * - Route
+     - Responsibility
+   * - ``/api/auth/[...all]``
+     - better-auth route handler.
+   * - ``/api/comments/[...comment]``
+     - Fuma Comments route handler.
+   * - ``/api/search``
+     - Public search index endpoint.
+   * - ``/rss.xml``
+     - Feed output.
+   * - ``/banner.png``
+     - Site-level Open Graph image.
+   * - ``/og/[...slug]``
+     - Post-specific Open Graph image.
+
+Routing Rule
+------------
+
+Add new public pages under ``src/app/(main)`` and preserve the existing layout
+split between the public site and Payload admin. New API routes should document
+their public contract in :doc:`../reference/api`.
diff --git a/Documentation/source/frontend/ui-guidelines.rst b/Documentation/source/frontend/ui-guidelines.rst
new file mode 100644
index 0000000..d3e8a9d
--- /dev/null
+++ b/Documentation/source/frontend/ui-guidelines.rst
@@ -0,0 +1,63 @@
+UI Guidelines
+=============
+
+Product Positioning
+-------------------
+
+The UI should feel like a content-first technical blog: readable, restrained,
+and efficient. It should avoid marketing-heavy layouts unless the page itself
+is explicitly promotional.
+
+Design Principles
+-----------------
+
+* Reading first: typography, line length, and contrast should favor long-form
+  reading.
+* Lightweight navigation: posts, tags, search, theme switching, and account
+  actions should remain easy to reach.
+* Consistent visual language: dashed borders, corner markers, and subtle
+  motion are part of the current identity.
+* Low learning cost: anonymous and authenticated flows should be obvious.
+* Cross-device consistency: mobile and desktop should share the same hierarchy.
+
+Visual Conventions
+------------------
+
+Typography
+   Use the configured Geist font family for prose and Geist Mono for code-like
+   metadata. Avoid oversized headings inside dense cards or sidebars.
+
+Color
+   Use existing design tokens from ``src/styles/globals.css``. The site
+   supports light, dark, and system theme modes.
+
+Shape
+   Prefer the existing dashed-border and corner-marker treatment for major
+   framed sections. Avoid adding unrelated decorative systems.
+
+Motion
+   Keep motion short, functional, and tied to state changes. Current examples
+   include hero fade-in, hover transitions, theme transition, and share toast.
+
+Page Notes
+----------
+
+Home
+   Hero, latest posts, and newsletter CTA should establish identity and expose
+   current content quickly.
+
+Post list
+   Cards should support scanning title, summary, tags, date, and image without
+   requiring a detail-page visit.
+
+Post detail
+   The article body is primary. Side metadata, share controls, and comments
+   should support the reading flow rather than compete with it.
+
+Tags
+   Tag pages should make topic discovery fast and preserve the post-list visual
+   pattern.
+
+Login
+   OAuth options should be clear and minimal. Do not add account-management
+   concepts to the login page unless the backend supports them.