achra-guidelines（阿克拉指南）

Achra Guidelines

Overview

Achra platform guidelines for architecture, conventions, business domains, and technical patterns. This skill covers where code lives, how to name and structure it, when to use feature flags, and how domains and routes map.

WIP: These guidelines are a draft. When a task is not covered here or in linked references, prefer consistency with existing Achra code and patterns.

When to Apply

Reference these guidelines when:

• Writing new code in the Achra codebase (components, pages, services, hooks, providers, etc)
• Writing or reviewing Storybook stories
• Creating skeleton loaders, loading placeholders, Suspense fallbacks, or Next.js loading.tsx
• Refactoring or reviewing code for Achra consistency
• Adding a new module, feature, or route
• Answering questions about Achra architecture, business domains, or conventions
• Deciding where to place a component or whether to add a feature flag
• Answering questions about Achra's tech stack or choosing libraries/tools

Quick Reference

Storybook stories

Stories serve two purposes: documentation for reusable/shared components and visual regression testing via Chromatic on every PR.

When to create a story: For section-level and page-level components, and for any reusable component (especially in modules/shared/). Skip one-time small components — write the story on the parent section component instead.

Variants: Only create variants that produce visually distinct UI states. Default, Loading, Empty, and Error cover most components. Avoid prop-permutation variants that look identical in Chromatic.

Key patterns:

• Colocate [component-name].stories.tsx next to the component file
• Import from @storybook/nextjs-vite
• Use layout: 'fullscreen' for sections, 'centered' for isolated components
• Use shared decorators from modules/shared/lib/decorators.tsx: withNuqsAdapter, withReactQueryProvider, withPortalFontStyles
• Mock API calls with MSW (parameters.msw.handlers); use delay('infinite') for the Loading variant
• Place mock data in modules/{module}/mocks/, not inline in story files
• Use tags: ['autodocs'] only on shared UI components

Full rules, patterns, and examples: storybook-stories.md.

Skeleton loading

Skeleton loading is an Achra pattern for loading states. Use it for route loading (loading.tsx), Suspense fallbacks, or any placeholder that should match the final layout to avoid shift.

Workflow: Locate the target UI → create a sibling {component-name}-skeleton.tsx → mirror structure and replace content with Skeleton elements sized to match → remove interactivity and data logic → validate layout parity and contrast.

Quick checklist:

• Mirror layout containers and responsive classes (sm:, md:, etc.).
• Replace text with Skeleton using line-height-derived heights; for multi-line with gap-1, subtract 2px per line to prevent layout shift.
• Remove buttons, links, state, effects, and data fetching.
• Use bg-border on skeletons inside bg-accent, bg-muted, or bg-secondary.
• Reuse existing skeleton subcomponents when available.

Required import: import {Skeleton} from '@/shared/components/ui/skeleton'

Full rules, sizing, contrast, and accessibility: skeleton-loading.md. Patterns and examples: skeleton-loading-examples.md.

References

Full documentation:

• achra-overview.md — Business and product context; main domains and where they live
• architecture.md — Module layout, shared vs domain, promotion rules, placement decision tree, imports
• conventions.md — Naming, component directories, exports
• feature-flags-and-env.md — When and where to use feature flags; env behavior
• data-and-graphql.md — GraphQL and services location; generated code
• tech-stack.md — Framework, UI, data, forms, and tooling used in the project
• storybook-stories.md — When to create stories, variant policy, file placement, title convention, decorators, MSW, mock data
• skeleton-loading.md — Skeleton loaders: layout mirroring, sizing, contrast, cleanup, validation
• skeleton-loading-examples.md — Skeleton patterns and code examples
• achra-guidelines.md — Human-facing index with table of contents and links
• rules/ — Granular rules (arch-, conv-, ff-, data-)