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)
• 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

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
• 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-)