Merge pull request #21 from bertyuan/Documentationv1.2

docs: add comprehensive documentation for operations

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.