chore: cleanup standards (#6970)

* chore: cleanup standards & skills

* remove: figma mcp doc, not needed anymore
This commit is contained in:
Calum H.
2026-08-10 15:15:44 +00:00
committed by GitHub
parent 98cb6b6b44
commit e8aee15664
39 changed files with 1271 additions and 1130 deletions
+35 -31
View File
@@ -1,8 +1,8 @@
# Component Structure
## Component folders
## Component Folders
Prefer giving non-trivial components their own folder:
Give each complex component its own folder:
```
components/
@@ -14,25 +14,25 @@ components/
└── use-analytics-chart.ts
```
The folder name should match the public component name in kebab case. The main component in that folder should be `index.vue`.
Use the public component name in kebab case for the folder name. Use `index.vue` for the main component.
This keeps imports short:
This structure keeps imports short:
```ts
import AnalyticsChart from '@/components/analytics-chart/index.vue'
```
If the local resolver supports directory indexes, importing the folder is also fine:
You can import the folder if the local resolver supports directory indexes:
```ts
import AnalyticsChart from '@/components/analytics-chart/'
```
Use the explicit `index.vue` import when the TypeScript setup cannot resolve the directory import reliably.
Use the explicit `index.vue` import if TypeScript cannot resolve the directory import.
## Local implementation files
## Local Implementation Files
Keep files that only exist to support one component inside that component's folder:
Keep files for only one component in that component's folder:
```
analytics-chart/
@@ -44,18 +44,18 @@ analytics-chart/
└── use-chart-hover-state.ts
```
Good candidates for local files:
Use local files for these items:
- Small subcomponents used only by the main component
- Local composables used only by the main component or its local subcomponents
- Helpers that split up a large `<script setup>` block
- Types that describe local component state or props
- Small subcomponents that only the main component uses.
- Local composables that only the component folder uses.
- Helpers that divide a large `<script setup>` block.
- Types for local component state or props.
This is preferred over allowing a single component file to grow into a large, hard-to-review script block.
This structure prevents large script blocks that are difficult to review.
## Naming local subcomponents
## Local Subcomponent Names
Local subcomponents should still have clear names that explain their relationship to the main component:
Use clear names that show the relation between each subcomponent and its main component:
```
analytics-chart/
@@ -64,7 +64,7 @@ analytics-chart/
└── analytics-chart-plot.vue
```
Avoid vague names that make a local component look like a standalone public component:
Do not use names that make a local component look like a public component:
```
analytics-chart/
@@ -73,13 +73,13 @@ analytics-chart/
└── header.vue
```
If a file is local to `analytics-chart`, prefixing it with `analytics-chart-` makes that relationship clear when it appears in search results, editor tabs, and imports.
Add the `analytics-chart-` prefix to local filenames. This prefix shows the relation in search results, editor tabs, and imports.
## Nesting
One level of nesting is usually enough.
Use one nesting level in most component folders.
Prefer this:
Use this structure:
```
analytics-chart/
@@ -90,7 +90,7 @@ analytics-chart/
└── use-chart-selection.ts
```
Avoid this unless a local area has become large enough to justify its own module boundary:
Do not use this structure unless a local area needs its own module boundary:
```
analytics-chart/
@@ -102,11 +102,13 @@ analytics-chart/
└── use-plot-state.ts
```
Subfolders are fine when they reduce real complexity, but do not create a folder for every small subcomponent by default. Deep nesting makes the file tree harder to scan and often adds duplicated names without improving ownership.
Use subfolders when they reduce real complexity. Do not make a folder for each small subcomponent.
## When not to use a folder
Deep nesting makes the file tree difficult to scan. It also causes duplicate names without clearer ownership.
Small, leaf components can stay as a single `.vue` file:
## Small Components
Keep small leaf components in single `.vue` files:
```
components/
@@ -115,14 +117,16 @@ components/
└── project-status-pill.vue
```
Move a component into a folder once it grows local helpers, local composables, or local subcomponents.
Move a component into a folder when it gets local helpers, composables, or subcomponents.
## Public versus local components
## Public and Local Components
Only the main `index.vue` should be treated as the public entry point for the folder. Other files in the folder are implementation details unless there is a clear reason to import them from outside.
Use only the main `index.vue` as the public entry point. Treat the other folder files as implementation details.
If a local subcomponent starts being imported elsewhere, either:
If another component imports a local subcomponent, use one of these solutions:
- Promote it into its own component folder
- Move it to the nearest shared component area if it is genuinely reusable
- Keep it local and pass behavior through the main component if external imports would leak implementation details
- Move the subcomponent into its own component folder.
- Move the subcomponent to the nearest shared component area when it is reusable.
- Keep it local and pass behavior through the main component.
Use the last solution when an external import exposes implementation details.