docs(readme): update project overview and instruction references, new instructions for csharp, dotnet, nuxt, vue and tailwindcss

Author: devbyray

.github/copilot-instructions.md

@@ -29,22 +29,25 @@ This repository contains guidelines and best practices for using GitHub Copilot
 
 ## 📚 Table of Contents
 
-- **UI Guidelines**: Accessibility, design system, and styling principles for consistent, usable, and maintainable user interfaces.
-  [Read more](./instructions/ui-guidelines.instructions.md)
-- **Project and Folder Structure**: Key directories and their roles in the project.  
-  [Read more](./instructions/project-file-structure.instructions.md)
-- **Tools, Libraries & Frameworks Instructions**: Core technologies, frameworks, and their versions used in this repository.  
-  [Read more](./instructions/tools.instructions.md)
-- **Coding Instructions**: Practical coding standards for JavaScript/TypeScript, CSS, and components, including semicolons, quotes, and function-based patterns.  
-  [Read more](./instructions/coding.instructions.md)
-- **Commit Message Instructions**: Conventional Commits format for clear, consistent commit messages.  
-  [Read more](./instructions/commit.instructions.md)
-- **Testing & TDD Instructions**: Test-driven development process, recommended tools, and test naming conventions.  
-  [Read more](./instructions/testing.instructions.md)
-- **Configuration Files Instructions**: Standards for configuration files such as .editorconfig, Prettier, and ESLint.  
-  [Read more](./instructions/config.instructions.md)
-- **Best Practices Instructions**: Universal coding principles (SOLID, DRY, KISS) for maintainable and efficient code.  
-  [Read more](./instructions/best-practices.instructions.md)
+  - Coding standards ([coding.instructions.md](.github/instructions/coding.instructions.md))
+  - Accessibility ([accessibility.instructions.md](.github/instructions/accessibility.instructions.md))
+  - CSS ([css.instructions.md](.github/instructions/css.instructions.md))
+  - Tailwind CSS ([tailwind.instructions.md](.github/instructions/tailwind.instructions.md))
+  - HTML ([html.instructions.md](.github/instructions/html.instructions.md))
+  - UI guidelines ([ui-guidelines.instructions.md](.github/instructions/ui-guidelines.instructions.md))
+  - Commit messages ([commit.instructions.md](.github/instructions/commit.instructions.md))
+  - Best practices ([best-practices.instructions.md](.github/instructions/best-practices.instructions.md))
+  - Configuration files ([config.instructions.md](.github/instructions/config.instructions.md))
+  - C# standards ([csharp.instructions.md](.github/instructions/csharp.instructions.md))
+  - .NET standards ([dotnet.instructions.md](.github/instructions/dotnet.instructions.md))
+  - JavaScript/TypeScript standards ([javascript-typescript.instructions.md](.github/instructions/javascript-typescript.instructions.md))
+  - Vue standards ([vue.instructions.md](.github/instructions/vue.instructions.md))
+  - Nuxt.js standards ([nuxt.instructions.md](.github/instructions/nuxt.instructions.md))
+  - Markdown standards ([markdown.instructions.md](.github/instructions/markdown.instructions.md))
+  - Project structure ([project-file-structure.instructions.md](.github/instructions/project-file-structure.instructions.md))
+  - Security ([security.instructions.md](.github/instructions/security.instructions.md))
+  - Testing & TDD ([testing.instructions.md](.github/instructions/testing.instructions.md))
+  - Tooling ([tools.instructions.md](.github/instructions/tools.instructions.md))
 
 ---
 

.github/instructions/csharp.instructions.md

@@ -0,0 +1,32 @@
+---
+description: C# coding standards and conventions for the project.
+applyTo: "**/*.cs"
+---
+
+# C# Coding Standards & Conventions
+
+## General Guidelines
+
+1. Use PascalCase for class, interface, enum, and method names.
+2. Use camelCase for local variables and parameters.
+3. Use explicit access modifiers (public, private, protected, internal) for all types and members.
+4. Prefer expression-bodied members for simple properties and methods.
+5. Use var for local variable declarations when the type is obvious from the right side of the assignment; otherwise, use the explicit type.
+6. Always use braces `{}` for all control flow statements (if, else, for, foreach, while, etc.), even for single statements.
+7. Use single quotes for char literals and double quotes for string literals.
+8. Prefer pattern matching and modern C# features where appropriate.
+9. Avoid magic numbers; use named constants or enums.
+10. Write XML documentation comments for public APIs, classes, and methods.
+11. End every statement with a semicolon.
+
+## Example
+
+```csharp
+/// <summary>
+/// Calculates the sum of two integers.
+/// </summary>
+public static int Add(int a, int b)
+{
+    return a + b;
+}
+```

.github/instructions/dotnet.instructions.md

@@ -0,0 +1,41 @@
+---
+description: .NET coding standards and conventions for the project.
+applyTo: "**/*.cs"
+---
+
+# .NET Coding Standards & Conventions
+
+## General Guidelines
+
+1. Organize code by feature or module, keeping related files together.
+2. Use solution folders to mirror the logical structure of the application.
+3. Use PascalCase for project, namespace, and folder names.
+4. Place using directives outside the namespace and sort them alphabetically.
+5. Use explicit access modifiers (public, private, protected, internal) for all types and members.
+6. Prefer dependency injection for service and resource management.
+7. Use async/await for asynchronous code.
+8. Avoid magic numbers; use named constants or enums.
+9. Write XML documentation comments for public APIs, classes, and methods.
+10. End every statement with a semicolon.
+11. Use .editorconfig to enforce consistent formatting.
+12. Avoid regions except for large files with clear logical separation.
+
+## Example
+
+```csharp
+using System;
+
+namespace MyApp.Services
+{
+    /// <summary>
+    /// Provides user-related operations.
+    /// </summary>
+    public class UserService : IUserService
+    {
+        public async Task<User> GetUserAsync(Guid id)
+        {
+            // ...implementation...
+        }
+    }
+}
+```

.github/instructions/nuxt.instructions.md

@@ -0,0 +1,72 @@
+---
+description: Coding standards and conventions for Nuxt.js projects in this repository.
+applyTo: "**/*.vue"
+---
+
+
+# Nuxt.js Coding Instructions
+
+For all general Vue coding standards, see [vue.instructions.md](./vue.instructions.md). Follow those rules for all Nuxt components and pages unless overridden below.
+
+## Nuxt-Specific Guidelines
+
+### Pages
+- Place all route pages in the `pages/` directory. File and folder names define the route structure automatically.
+- Use `<script setup>` at the top of each page file, followed by `<template>`, then `<style scoped>`.
+- Use TypeScript for all pages when possible.
+
+### Layouts
+- Place shared layouts in the `layouts/` directory. Use the `default.vue` layout for the main app shell.
+- Use the `<NuxtLayout />` component to switch layouts dynamically.
+- Use the `definePageMeta` composable to set page-specific metadata.
+
+### Auto-Import Components
+- Place reusable components in the `components/` directory. Nuxt auto-imports components, so you do not need to manually import them in your templates.
+- Use PascalCase for component file names and references in templates.
+
+### Composables
+- Place composable functions in the `composables/` directory. Nuxt auto-imports composables that start with `use` (e.g., `useAuth`).
+- Use Nuxt composables such as `useRoute`, `useRouter`, `useAsyncData`, and `useFetch` for routing and data fetching.
+
+### Directory Structure
+- Organize your app using Nuxt's conventions: `pages/`, `layouts/`, `components/`, `composables/`, `stores/`, and `middleware/`.
+
+### Example Page Component
+
+```vue
+<script setup lang='ts'>
+import { ref } from 'vue';
+import { useRoute } from 'route';
+
+const route = useRoute();
+const count = ref(0);
+
+const increment = () => {
+  count.value++;
+};
+</script>
+
+<template>
+  <section>
+    <h2>Welcome to Nuxt!</h2>
+    <p>Current route: {{ route.path }}</p>
+    <button @click="increment">Clicked {{ count }} times</button>
+  </section>
+</template>
+
+<style scoped>
+section {
+  padding: 2rem;
+}
+button {
+  font-size: 1rem;
+  margin-top: 1rem;
+}
+</style>
+```
+
+## References
+- [Nuxt 3 Documentation](https://nuxt.com/docs)
+- [Nuxt 3 Directory Structure](https://nuxt.com/docs/guide/directory-structure/nuxt)
+- [Vue.js Style Guide](https://vuejs.org/style-guide/)
+- [Vitest for Vue/Nuxt Testing](https://vitest.dev/)

.github/instructions/tailwind.instructions.md

@@ -0,0 +1,128 @@
+---
+description: Tailwind CSS usage and configuration standards for this repository.
+applyTo: "**/*.{css,vue,js,ts,jsx,tsx}"
+---
+
+# Tailwind CSS Instructions
+
+## Version
+- Use Tailwind CSS v4 or higher. Do not use older versions.
+- Tailwind v4+ does not use `@config` or JavaScript/TypeScript config files. All configuration is handled via CSS and utility classes.
+
+## Customizing Colors
+- To use custom colors, use Tailwind's built-in color palette and utility classes (e.g., `bg-blue-600`, `text-primary`).
+- For custom colors, you can:
+  - Use the `style` attribute for one-off values.
+  - Do not use arbitrary color values (e.g. `bg-[#0ea5e9]`). Always use colors defined in your `@theme` block for consistency and maintainability.
+  - Define custom CSS variables with the `@theme` directive and use them in your utility classes.
+
+### Example: Customizing Colors with @theme
+
+```css
+@import "tailwindcss";
+@theme {
+  --color-midnight: #121063;
+  --color-tahiti: #3ab7bf;
+  --color-bermuda: #78dcca;
+}
+
+.btn-tahiti {
+  @apply bg-[--color-tahiti] text-white font-semibold px-4 py-2 rounded;
+}
+```
+
+```vue
+<template>
+  <button class="btn-tahiti hover:bg-[--color-bermuda]">Custom Color</button>
+</template>
+```
+
+See the [Tailwind CSS Colors documentation](https://tailwindcss.com/docs/colors) for more details on using and customizing colors.
+
+## Usage
+- Use Tailwind utility classes directly in your HTML, Vue, or JSX/TSX templates.
+- Prefer semantic and accessible markup; combine Tailwind with best practices from the HTML and accessibility instructions.
+- To use `@apply` in a Vue component's `<style>` block, you must reference TailwindCSS at the top of the style section:
+
+  ```vue
+  <template>
+    <h1>Hello world!</h1>
+  </template>
+  <style>
+    @reference "tailwindcss";
+    h1 {
+      @apply text-2xl font-bold text-red-500;
+    }
+  </style>
+  ```
+- Use `@apply` for extracting repeated utility patterns into custom classes in your CSS modules or component styles.
+- Do not override Tailwind base styles globally unless absolutely necessary.
+
+## Best Practices
+- Keep utility class lists short and readable; extract to custom classes if they become too long.
+- Use responsive and state variants (e.g., `md:`, `hover:`) as needed for interactivity and layout.
+- Use Tailwind's color palette and spacing scale for consistency.
+- Avoid using arbitrary values. Always use colors and spacing defined in your `@theme` block or Tailwind's default palette for consistency.
+- Do not use deprecated or removed features from earlier Tailwind versions.
+
+
+## Example
+
+
+### Custom Components with @layer
+
+To add custom component classes (such as buttons or cards), use the `@layer components` directive:
+### Custom Utilities with @utility
+
+To define custom utility classes, use the `@utility` directive:
+
+```css
+@utility content-auto {
+  content-visibility: auto;
+}
+```
+
+```css
+@import "tailwindcss";
+@theme {
+  --color-white: #fff;
+  --radius-lg: 0.5rem;
+  --spacing-6: 1.5rem;
+  --shadow-xl: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1);
+}
+
+@layer components {
+  .card {
+    background-color: var(--color-white);
+    border-radius: var(--radius-lg);
+    padding: var(--spacing-6);
+    box-shadow: var(--shadow-xl);
+  }
+  .btn-primary {
+    @apply px-4 py-2 rounded bg-[--color-primary] text-white font-semibold hover:bg-[--color-primary-hover];
+  }
+}
+```
+
+### Variants with @variant
+
+To define variants (such as dark mode), use the `@variant` directive:
+
+```css
+.my-element {
+  background: white;
+  @variant dark {
+    background: black;
+  }
+}
+```
+
+```vue
+<template>
+  <div class="card">Card content</div>
+  <button class="btn-primary">Click me</button>
+</template>
+```
+
+## References
+- [Tailwind CSS v4 Documentation](https://tailwindcss.com/docs/installation)

.github/instructions/vue.instructions.md

@@ -0,0 +1,66 @@
+---
+description: Coding standards and conventions for Vue.js projects in this repository.
+applyTo: "**/*.vue"
+---
+
+# Vue.js Coding Instructions
+
+## General Guidelines
+
+1. Use Vue 3 with the Composition API for all new components.
+2. Organize code by feature/module; keep related files together.
+3. Use single-file components (`.vue`) with `<script setup>`, `<template>`, and `<style scoped>` sections (in that order).
+4. Place the `<script setup>` section at the top of the file, followed by `<template>`, then `<style scoped>` at the bottom.
+5. Prefer `<script setup>` syntax for simplicity and type inference.
+5. Use TypeScript in Vue components when possible.
+6. Use PascalCase for component names and file names (e.g., `MyComponent.vue`).
+7. Use kebab-case for custom event names and props in templates.
+8. Always define `props` with types and default values where appropriate.
+9. Use `defineEmits` and `defineProps` for event and prop definitions.
+10. Use `ref` and `reactive` for state; avoid using `this`.
+11. Use `v-bind` and `v-on` shorthand (`:` and `@`) in templates.
+12. Use `v-if`/`v-else` for conditional rendering and `v-for` for lists; always provide a unique `:key` for `v-for`.
+13. Avoid logic in templates; keep templates declarative and move logic to the script section.
+14. Use composables (`useXyz`) for reusable logic.
+15. Write clear JSDoc/TSDoc comments for composables and complex logic.
+16. Use CSS modules or `<style scoped>` for component styles; avoid global styles.
+17. Follow accessibility and UI guidelines for all components.
+18. End every statement with a semicolon and use single quotes for strings.
+19. Avoid using `any` type; prefer explicit types.
+20. Write unit tests for all components using Vitest.
+
+
+## Example Component
+
+```vue
+<script setup lang='ts'>
+import { defineProps, defineEmits } from 'vue';
+
+const props = defineProps<{
+  disabled?: boolean;
+}>();
+const emit = defineEmits<{ (e: 'click'): void }>();
+
+const onClick = () => {
+  if (!props.disabled) emit('click');
+};
+</script>
+
+<template>
+  <button @click="onClick" :disabled="disabled">
+    <slot />
+  </button>
+</template>
+
+<style scoped>
+button {
+  font-size: 1rem;
+  padding: 0.5em 1em;
+}
+</style>
+```
+
+## References
+- [Vue.js Style Guide](https://vuejs.org/style-guide/)
+- [Vue 3 Documentation](https://vuejs.org/)
+- [Vitest for Vue Testing](https://vitest.dev/)