This is an automated email from the ASF dual-hosted git repository.

fenbox pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/answer.git


The following commit(s) were added to refs/heads/main by this push:
     new 9e6ca4a0 docs: add repository and design guidelines (#1678)
9e6ca4a0 is described below

commit 9e6ca4a01d2462491323dbe04cd14ec34303e503
Author: Fen <[email protected]>
AuthorDate: Thu Nov 19 15:26:21 2026 +0800

    docs: add repository and design guidelines (#1678)
    
    ## Proposed Changes
    
    - Add `AGENTS.md` with repository structure, development commands,
    coding conventions, testing guidance, and commit/PR expectations.
    - Add an English `DESIGN.md` following the design.md alpha
    specification, documenting React Bootstrap as the design foundation and
    the default primary color `#0033FF`.
    - Document existing theme overrides, dark mode, layout conventions, and
    component usage, with YAML design tokens and source references.
    
    ## Validation
    
    - Checked commands and conventions against repository configuration and
    source files.
    - Confirmed `DESIGN.md` contains no Chinese text.
    - `git diff --cached --check` passed before committing.
    - Documentation-only changes; no application tests run.
---
 AGENTS.md | 31 ++++++++++++++++++++
 DESIGN.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..c2f36934
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,31 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Apache Answer combines a Go backend with a React/TypeScript frontend. 
`cmd/answer` is the executable entry point; `internal/` contains controllers, 
services, repositories, schemas, and migrations. Shared Go utilities live in 
`pkg/`, and extension interfaces live in `plugin/`. Frontend pages, components, 
stores, and API clients are under `ui/src/`; static assets are in `ui/public/`, 
and production output is embedded from `ui/build/`. Translations live in 
`i18n/`, configuration examples in [...]
+
+## Build, Test, and Development Commands
+
+Use Go 1.25+, Node.js matching `ui/package.json` (`^20.19.0 || >=22.12.0`), 
and pnpm 9.7.0. `make lint` also requires Docker or Podman installed and 
running for the ASF header formatter.
+
+- `make generate`: install generators, regenerate Go code/API documentation, 
and tidy modules.
+- `make ui`: install frontend dependencies and build the UI.
+- `make build`: regenerate code and build the `answer` executable.
+- `./answer init -C ./data` then `./answer run -C ./data`: initialize and run 
locally.
+- Before `cd ui && pnpm start` (Vite, port 3000), set 
`REACT_APP_API_URL=http://localhost:8080/` in `ui/.env.development.local`, 
matching your backend address. This overrides the checked-in private proxy 
target; restart Vite after changes.
+- `make test`: run repository integration tests.
+- `go test ./...`: run the full Go test suite.
+- `make lint`: regenerate code, check ASF headers, and run golangci-lint.
+- `cd ui && pnpm lint`: run ESLint with automatic fixes; `pnpm prettier` 
formats frontend sources.
+
+## Coding Style & Naming Conventions
+
+Format Go with `gofmt`; use tabs and conventional exported `PascalCase` names. 
Follow existing snake_case Go filenames and package organization. Frontend code 
uses two spaces, single quotes, trailing commas, and an 80-column Prettier 
target. Use PascalCase component directories and follow neighboring files. 
Respect `.editorconfig`, ESLint, and ASF license headers. Regenerate generated 
files through tooling rather than editing them manually.
+
+## Testing Guidelines
+
+Use Go's `testing` package and existing Testify assertions. Name files 
`*_test.go` and functions `TestXxx`. Add regression coverage for changed 
behavior. Repository tests default to SQLite; MySQL/PostgreSQL variants use 
`TEST_DB_DRIVER` and Docker. No fixed coverage threshold or frontend test 
script is configured; verify UI changes with `pnpm build` and browser checks.
+
+## Commit & Pull Request Guidelines
+
+Follow history's conventional prefixes: `fix:`, `feat:`, `build:`, `test:`, or 
`chore:`, with optional scope, such as `fix(security): enforce visibility`. 
Keep commits focused. Follow the PR template: link the issue with `Fixes #...` 
and describe proposed changes. Include validation results and screenshots for 
visible UI changes. Review generated changes before committing; CI checks 
linting and unexpected generated diffs.
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 00000000..91923698
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,98 @@
+---
+version: alpha
+name: Apache Answer
+description: A React Bootstrap interface for Q&A communities, branded through 
the primary color.
+omitted:
+  - section: typography
+    reason: Inherits Bootstrap typography without separate brand typography 
tokens.
+  - section: spacing
+    reason: Uses Bootstrap spacing utilities and existing page layouts without 
a separate spacing scale.
+  - section: rounded
+    reason: Inherits default Bootstrap component radii.
+  - section: motion
+    reason: Inherits Bootstrap and React Bootstrap component transitions.
+---
+
+# Apache Answer Design System
+
+## Overview
+
+Apache Answer supports Q&A communities and knowledge sharing. Keep the 
interface clear and practical, prioritizing readable questions, answers, and 
actions.
+
+The foundation is **React Bootstrap 2.10.6 + Bootstrap 5.3.3** (currently 
locked versions). Brand customization changes only the primary color. Component 
structure, sizing, typography, radii, and interactions follow Bootstrap 
defaults. Reuse existing domain styles and layouts without expanding them into 
a separate component design system.
+
+Dependency sources: `@ui/package.json` and `@ui/pnpm-lock.yaml`. Global 
stylesheet entry point: `@ui/src/index.scss`.
+
+## Colors
+
+The default brand primary is **Answer Blue / `#0033FF`**, used for primary 
actions, links, selected states, and branded navigation. Success, warning, 
danger, secondary actions, and neutrals retain Bootstrap semantic colors. Do 
not turn every state blue.
+
+```yaml
+colors:
+  primary: "#0033FF"
+```
+
+This token represents the default theme. The site setting 
`theme_config[theme].primary_color` can override the active primary color. 
Design previews should reflect the target site's configuration.
+
+At build time, `@ui/src/common/_variable.scss` sets the default primary 
through `$blue` before Bootstrap is imported. At runtime, 
`@ui/src/components/CustomizeTheme/index.tsx` synchronizes primary colors, 
links, buttons, pagination, selected items, and form focus states. Reuse this 
mechanism to derive hover, active, focus, and disabled states instead of 
introducing isolated color values.
+
+Light and dark modes use `data-bs-theme`. Bootstrap semantic variables and 
`@ui/src/common/color.scss` adapt surfaces, text, and borders. Dark mode links 
use lighter primary shades derived by the existing theme logic. Avoid hardcoded 
light backgrounds in components.
+
+## Typography
+
+Use Bootstrap's default system font stack, sizes, weights, and line heights. 
Establish hierarchy with semantic headings, body text, and existing utilities 
such as `small`. Keep the existing typography scale and system fonts. Project 
utilities such as `.small` and `.fs-12` follow their global stylesheet 
definitions.
+
+Long questions, answers, and code should wrap or scroll locally without 
overflowing the page. Preserve semantic headings, form labels, and body 
structure.
+
+## Layout
+
+Use Bootstrap responsive containers, grids, breakpoints, and spacing 
utilities. Reuse neighboring page layouts first. Pages typically combine 
navigation, main content, and an optional sidebar. Stack content naturally on 
narrow screens and keep primary actions accessible.
+
+The existing sidebar layout is defined in `@ui/src/common/sideNavLayout.scss`: 
`.main-mx-with` has a maximum width of `1072px`; `.page-right-side` has a 
desktop width of `300px` and becomes full width below `1199.9px`. Inherit these 
values when using that layout, rather than imposing them on every page.
+
+## Elevation & Depth
+
+Use Bootstrap borders, surface layers, and default overlay styles to 
distinguish regions. Preserve the existing navigation shadow. Keep ordinary 
content areas free of additional decorative shadows. Dropdowns, tooltips, and 
modals follow component defaults for stacking and positioning.
+
+## Shapes
+
+Buttons, inputs, cards, and modals retain Bootstrap default radii and borders. 
Domain elements such as avatars and tags reuse their existing component shapes. 
Do not apply a universal pill or square treatment.
+
+## Motion & Micro-interaction
+
+Use React Bootstrap's built-in collapse, fade, and component state feedback. 
Preserve default transition timing and honor `prefers-reduced-motion`. Avoid 
decorative looping animation. Asynchronous actions should communicate loading 
and prevent duplicate submission.
+
+## Voice & Content Strategy
+
+Write direct, friendly copy with clear action names and consistent Q&A 
terminology. Reuse existing translation keys in `i18n/`. Add new copy through 
the internationalization workflow rather than hardcoding a single language in 
components.
+
+Action labels describe outcomes, such as “Post question” and “Save changes.” 
Empty states explain what is missing and suggest a next step. Errors explain 
the failure and an actionable remedy. Dates, numbers, and capitalization follow 
the active locale and neighboring interfaces.
+
+## Components
+
+Prefer components exported by `react-bootstrap` and reuse existing domain 
wrappers in `ui/src/components/`.
+
+- **Buttons:** Use `Button variant="primary"` for primary actions. Use 
existing secondary, outline, or link variants for secondary actions. Preserve 
danger semantics for destructive actions.
+- **Forms:** Use standard `Form`, `Form.Control`, and `Form.Select` 
components. Keep labels, help text, validation messages, and visible focus. 
Checked states and focus colors follow the theme.
+- **Navigation and pagination:** Reuse Nav, Navbar, Dropdown, and Pagination. 
Selected states follow primary; sizing and keyboard behavior follow component 
defaults.
+- **Content and feedback:** Reuse Card, ListGroup, Alert, Modal, and Tooltip. 
Question tags retain existing tag components and `.badge-tag` styling.
+- **Icons:** Use the project's existing Bootstrap Icons. Give icon buttons 
accessible names.
+
+These tokens describe only the brand color mapping for default primary 
buttons. Bootstrap supplies other properties, and the existing theme 
implementation derives interaction states.
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+  button-outline-primary:
+    textColor: "{colors.primary}"
+```
+
+## Do's and Don'ts
+
+- Prefer component props, Bootstrap utilities, and semantic CSS variables.
+- Maintain primary at the theme entry points; avoid repeating hardcoded 
`#0033FF` in domain components.
+- Preserve hover, focus, active, disabled, loading, and validation states.
+- Check light mode, dark mode, narrow screens, and keyboard interaction. Keep 
text, icons, and focus indicators clearly visible.
+- Keep the existing font, radius, shadow, spacing, and button systems.
+- Preserve danger, success, and warning semantics. Communicate status through 
more than color alone.

Reply via email to