|
1 | | -# Copilot / AI agent instructions (project-specific) |
| 1 | +# Copilot / AI instructions |
2 | 2 |
|
3 | | -This file contains focused, actionable rules for automated coding agents working in the KR_Portf repository. Keep guidance short and specific — prefer small, safe edits and follow the project's conventions. |
| 3 | +## Architecture |
4 | 4 |
|
5 | | -## Quick architecture & big picture |
6 | | -- Vite + React + TypeScript front-end served via Firebase Hosting. Entry points: `src/main.tsx` → `src/App.tsx` → `src/AppRouter.tsx`. |
7 | | -- UI components: `src/components/`; page sections: `src/sections/`; content/data: `src/data/` (e.g., `build.ts`, `projects.ts`). |
8 | | -- Theme and context providers: `src/providers/ThemeProvider.tsx`, `src/providers/theme-context.ts` and hook `src/hooks/useTheme.ts`. |
9 | | -- Tests and visual checks: Playwright + Vitest under `tests/` and `playwright.config.ts`. |
| 5 | +- Astro + React + TypeScript portfolio template. |
| 6 | +- Astro routes live in `src/pages/` (`index.astro`, `privacy-policy.astro`). |
| 7 | +- Main UI and section composition remain in React (`src/App.tsx`, `src/sections/*`). |
| 8 | +- Local content lives in `src/data/*` and translations in `src/translations/*`. |
10 | 9 |
|
11 | | -## Project-specific conventions (follow these) |
12 | | -- Compose Tailwind utility classes directly in JSX. Use PascalCase for components and camelCase for hooks. |
13 | | -- Visual style: rounded Material-like cards (`rounded-3xl`, `shadow-card`), warm orange/pink accents (`#f97316`, `#ec4899`), and `.font-kiya` for the printed name "Kiya Rose" (font located in `public/fonts`). |
14 | | -- Respect `prefers-reduced-motion`. Framer Motion is used; prefer short fade/slide transitions and provide reduced-motion fallbacks. |
15 | | -- Footer/legal: use `getBuildUpdatedAt()` from `src/data/build.ts` for the "Last updated" date — do not hard-code timestamps. |
16 | | -- Contact form: client-only `mailto:` generation plus copy-to-clipboard CTA (see `src/sections/ContactSection.tsx`). |
| 10 | +## Core conventions |
17 | 11 |
|
18 | | -## Environment & secrets |
19 | | -- Environment variables use the `VITE_` prefix. Critical: `VITE_TURNSTYLE_SITE` is intentionally misspelled (no second "t"); do not rename it. |
20 | | -- Never commit secrets. Use `.env.local` locally and GitHub Secrets in CI. |
| 12 | +- Keep the current visual layout and section order unless explicitly asked to redesign. |
| 13 | +- Prefer small, focused edits; preserve accessibility and reduced-motion behavior. |
| 14 | +- Use Tailwind utility classes in JSX and keep Material-like rounded card styling. |
| 15 | +- Use `.font-kiya` for the display-name accent style. |
21 | 16 |
|
22 | | -## Common developer workflows & commands |
23 | | -- Install deps: `npm ci` or `npm install`. |
24 | | -- Dev server: `npm run dev` (Vite, http://localhost:5173). |
25 | | -- Lint: `npm run lint` (run before PR). |
26 | | -- Build: `npm run build` → `dist/` for Firebase Hosting. |
27 | | -- Local hosting preview: `firebase emulators:start --only hosting` (project has `firebase.json`). |
28 | | -- Run tests: `npm run test` (Playwright tests and other test runners configured in package.json). |
| 17 | +## Remote data contract |
29 | 18 |
|
30 | | -## Places to inspect for examples and patterns |
31 | | -- Routing & layout: `src/App.tsx`, `src/AppRouter.tsx`. |
32 | | -- Footer/build label: `src/components/SiteFooter.tsx`, `src/data/build.ts` (localStorage prefix behavior). |
33 | | -- Contact flow: `src/sections/ContactSection.tsx` (mailto + clipboard behaviour). |
34 | | -- Theme logic: `src/providers/ThemeProvider.tsx`, `src/hooks/useTheme.ts`. |
35 | | -- Page-level sections: `src/sections/*` — follow their existing patterns for spacing, animation, and accessibility. |
| 19 | +- `VITE_REMOTE_DATA_URL` enables remote JSON fetches. |
| 20 | +- If no remote URL is set, use local fallback data only. |
| 21 | +- On remote fetch failure, show placeholder data (do not silently swap to local fallback). |
| 22 | +- Keep this behavior centered in `src/hooks/useRemoteData.ts`. |
36 | 23 |
|
37 | | -## Editing guidance for AI agents |
38 | | -- Make smallest useful change. Prefer a focused PR per issue. |
39 | | -- Preserve existing UX and data flows. If you change `src/data/build.ts` or footer code, preserve the localStorage build-label behavior unless explicitly fixing it. |
40 | | -- Avoid global CSS: adhere to Tailwind utility usage in JSX. |
41 | | -- When adding routes: update `src/AppRouter.tsx` and use `src/utils/navigation.ts` helpers. |
| 24 | +## Build and test commands |
42 | 25 |
|
43 | | -## Tests & quality gates |
44 | | -- Before proposing changes: run `npm run lint` and `npm run build` locally. |
45 | | -- Test files live under `tests/` (e.g. `a11y.spec.ts`, `screenshot.spec.ts`); Playwright is used for integration/visual checks. |
| 26 | +- Install: `npm ci` |
| 27 | +- Dev: `npm run dev` |
| 28 | +- Lint/type check: `npm run lint` |
| 29 | +- Unit tests: `npm run test` |
| 30 | +- E2E tests: `npm run test:e2e` |
| 31 | +- Build: `npm run build` |
46 | 32 |
|
47 | | -## Native companion tool |
48 | | -- `$DashCam!/` holds a macOS Swift helper app used by developers to manage dev and playwright codegen tasks. If you modify related scripts, update the DashCam Swift sources under `$DashCam!/Sources/DashboardApp`. |
| 33 | +## Deploy targets |
49 | 34 |
|
50 | | -## PR checklist for automated changes |
51 | | -- Lint passes (`npm run lint`). |
52 | | -- Build succeeds (`npm run build`). |
53 | | -- No secrets committed. |
54 | | -- Follow naming and Tailwind conventions. |
| 35 | +- Cloudflare Pages: output `dist/`, config in `wrangler.toml`, headers in `public/_headers`. |
| 36 | +- GitHub Pages: use `npm run build:pages` with `BASE_PATH=/your-repo-name/`. |
55 | 37 |
|
56 | | -If any section is unclear or you want more repo file examples, say which area to expand and I will iterate. |
57 | | -# Copilot Instructions |
| 38 | +## Security |
58 | 39 |
|
59 | | -## Style & Architecture |
60 | | - |
61 | | -- Keep the interface sleek and minimal with rounded Material-style cards, soft shadows, and translucent layers when depth is needed. |
62 | | -- Accent colors lean warm orange/pink (`#f97316` / `#ec4899`) in light mode while dark mode stays slate—mirror those tones in new UI or gradients. |
63 | | -- Use rounded Material Symbols for navigation, section headers, and social chips so iconography stays cohesive. |
64 | | -- Compose Tailwind utility classes directly in JSX; components follow PascalCase, hooks use camelCase, and class names remain lowercase-kebab. |
65 | | -- Respect `prefers-reduced-motion`, keeping Framer Motion animations subtle (short fade/slide transitions) and providing fallbacks for reduced motion preferences. |
66 | | -- Maintain the light/dark theme toggle with animated sun/moon icons and ensure contrast targets accessibility best practices. |
67 | | -- Apply the `.font-kiya` (Patrick Hand) accent whenever “Kiya Rose” appears in UI copy. |
68 | | -- Keep the footer’s legal line consistent: dynamic current year, typographic © symbol, `.font-kiya` "Kiya Rose", and the “Crafted with React, Tailwind CSS, and Firebase.” tag. |
69 | | -- Privacy and legal copy should source their “Last updated” value from `getBuildUpdatedAt()` in `src/data/build.ts` so the date reflects the current build—no hard-coded timestamps. |
70 | | -- Everything should be in Canadian English or French English when possible, when there are conflicting versions of a singular term use the more specific one. (For example cheque instead of check) |
71 | | - |
72 | | -## Environment Variables |
73 | | - |
74 | | -- Secrets use the `VITE_` prefix; note that `VITE_TURNSTYLE_SITE` (missing the second "t") is intentional and should not be renamed to `VITE_TURNSTILE_SITE`. |
75 | | - |
76 | | -## Quality Expectations |
77 | | - |
78 | | -- Prefer fixes that resolve lint warnings, TypeScript errors, and obvious UX problems rather than adding placeholders. |
79 | | -- When you touch code, scan the surrounding logic for latent bugs or smells and address them when feasible. |
80 | | -- Align fixes with the guidance used by DeepSource, CodeFactor, and SonarQube: eliminate dead code, handle edge cases, simplify complex conditionals, and tighten null/undefined guards. |
81 | | -- Preserve Firebase secrets by loading them from environment configuration—never commit credentials or hard-coded API keys. |
82 | | -- Ensure licensing references match the BSD 3-Clause notice in the project root `LICENSE` (copyright © 2025, Kiya Rose). |
83 | | -- Honor existing lint rules (avoid inline arrow handlers in JSX, limit nesting by extracting helpers, etc.). |
84 | | - |
85 | | -## Collaboration Notes |
86 | | - |
87 | | -- Favor small, composable helper components over deeply nested JSX trees (see `SiteHeader`/`SiteFooter` in `App.tsx`). |
88 | | -- When making UI changes, consider drag-and-drop persistence, localStorage access, the `mailto:` contact workflow, and other side effects already established in the repo. |
89 | | -- Use the existing `isDeveloping` styling in the Skills section when introducing new abilities (dashed border for in-progress skills). |
90 | | -- Keep the fallback page (`public/index.html`) visually aligned with the main palette when adjusting colors. |
91 | | -- Run `npm run lint` and (when relevant) `npm run build`; clean up generated `dist/` outputs if you run the build locally. |
92 | | -- Keep the build label helper in `src/data/build.ts` intact: it persists a random prefix per build signature in `localStorage`, so only adjust it if that behaviour breaks, and retain the accent tooltip that explains the two segments. |
93 | | -- Keep the macOS Swift companion `DashCam!` in `$DashCam!/`: it manages `npm run dev` and `npx playwright codegen` processes, so update `DashboardViewModel`/`ProcessController` plus the packaged `DashCam.app` or `dashcam_swift.tgz` whenever those workflows change. |
94 | | -- Route-level additions should flow through `src/AppRouter.tsx` with helpers from `src/utils/navigation.ts`; render privacy/legal pages inside React rather than shipping standalone static HTML. |
95 | | -- When you adjust repository guidance, update both `AGENTS.md` and this file so instructions stay in sync. |
96 | | -## Security & ZAP Scanning |
97 | | - |
98 | | -- All security headers are centrally configured in `security-headers.config.ts` and deployed via `public/_headers` (Cloudflare Pages), `firebase.json` (Firebase Hosting), and `vite.config.ts` (local preview). |
99 | | -- The ZAP workflow scans `https://your.website` nightly; check `.zap-ignore` for known/accepted alerts. |
100 | | -- When ZAP reports issues, verify headers are in `public/_headers` and deployed properly before adding to `.zap-ignore`. |
101 | | -- Use `safeConsoleWarn()` and `safeConsoleError()` from `src/utils/errorSanitizer.ts` instead of raw console methods to prevent information disclosure. |
| 40 | +- Keep security headers centralized in `security-headers.config.ts`. |
| 41 | +- Keep parity checks working via `npm run verify:security-headers`. |
| 42 | +- Use safe logging helpers in `src/utils/errorSanitizer.ts`. |
0 commit comments