Skip to content

Latest commit

 

History

History
418 lines (329 loc) · 9.18 KB

SWPT.md

File metadata and controls

418 lines (329 loc) · 9.18 KB

Sport Wales Project Template (SWPT)

Welcome to the Sport Wales Project Template - a comprehensive foundation for building React applications that align with Sport Wales' design system and development standards. This template combines Vite, React, Tailwind CSS, and our custom component library to help you build consistent, high-quality applications.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (version 18 or higher)
  • npm (comes with Node.js)
  • Git for version control
  • A code editor (we recommend VS Code)

Creating Your Project

  1. Clone the template:
git clone https://github.com/sportwales/SWPT.git your-project-name
cd your-project-name

  1. Update project configuration:

    • Open package.json and update: 
      {
  "name": "your-project-name",
  "version": "0.0.1",
  // Keep other configurations as is
}
    • Update the title in index.html
    • Remove the Git history and initialise a new repository: 
      rm -rf .git
git init

  2. Install dependencies:

npm install
  1. Start development:
npm run dev

Project Architecture

Directory Structure

your-project/
├── public/                    # Static assets
│   ├── sport_wales_logo_white.png
│   ├── sw_favicon.ico
│   └── vite.svg
├── src/
│   ├── components/           # React components
│   │   ├── component_library/  # Reusable UI components
│   │   ├── main/              # Core components
│   │   └── ui/                # Basic UI elements
│   ├── pages/                # Page components
│   ├── assets/               # Project assets
│   ├── data/                 # Data files
│   ├── styles/               # CSS styles
│   │   ├── index.css          # Main styles
│   │   └── custom/            # Custom styles
│   ├── utils/                # Utility functions
│   ├── App.jsx              # Main application
│   └── main.jsx             # Entry point
└── [Configuration Files]     # Various config files

Key Features

1. Styling System

The template uses a combination of Tailwind CSS and custom Sport Wales styles:

  • Sport Wales brand colors (configured in tailwind.config.js)
  • Custom components with consistent styling
  • Responsive design utilities
  • CSS variables for brand consistency

2. Component Library

Located in src/components/component_library/:

  • Pre-built components following Sport Wales design guidelines
  • Form components with validation
  • Layout components
  • Interactive elements

3. Bilingual Support

Built-in support for English and Welsh:

  • Route-based language switching
  • Language toggle component
  • Structured content organisation

4. Development Tools

  • Hot Module Replacement with Vite
  • ESLint configuration for code quality
  • PostCSS for advanced CSS features
  • Tailwind CSS for utility-first styling

Customisation Guide

Adding New Features

  1. Page Components:
// src/pages/YourNewPage.jsx
import React from 'react';
import { Layout } from '../components/Layout';

export function YourNewPage() {
  return (
    <Layout>
      <div className="sw-container">
        {/* Your content here */}
      </div>
    </Layout>
  );
}
  1. Add the route in App.jsx:
<Route path="/your-path" element={<YourNewPage />} />

Understanding the Style System

Base Styling Architecture

Our styling system combines Tailwind CSS with Sport Wales' custom design system. Think of it as a layered approach:

  1. Tailwind Base Layer: The foundation
  2. Sport Wales Custom Variables: Our brand-specific values
  3. Component-Specific Styles: Pre-built, consistent components
  4. Utility Classes: Quick style modifications

How Our Style System Works

CSS Variables and Brand Colors

In src/styles/index.css, we define our brand-specific CSS variables:

:root {
  /* Primary Brand Colors */
  --color-sw-red: #E32434;
  --color-sw-yellow: #F6B207;
  --color-sw-blue: #164B64;
  --color-sw-green: #299D91;

  /* Typography */
  --font-primary: 'Objektiv MK1', 'Montserrat', Arial, sans-serif;
  --font-size-body: 16px;
  --line-height-normal: 110%;
}

These variables are then integrated with Tailwind in tailwind.config.js:

export default {
  theme: {
    extend: {
      colors: {
        'sw-red': '#E32434',
        'sw-blue': '#164B64',
        // other colors...
      },
      fontSize: {
        'body': '20px',
        'hero': '95px',
      }
    }
  }
}

Using the Style System

  1. Basic Component Styling:
// Using Sport Wales utility classes
<button className="sw-button-primary">
  Click Me
</button>

// Same button with additional Tailwind utilities
<button className="sw-button-primary mt-4 hover:opacity-80">
  Click Me
</button>
  1. Layout Components:
// Sport Wales container with Tailwind spacing
<div className="sw-container py-8">
  <div className="sw-card">
    Content here
  </div>
</div>
  1. Text Styling:
// Combining Sport Wales and Tailwind classes
<h1 className="sw-heading-primary text-sw-blue mb-6">
  Main Heading
</h1>

Custom Components and Overrides

Our @layer components defines Sport Wales-specific components:

@layer components {
  .sw-button {
    height: var(--button-height);
    padding: var(--button-padding);
    border-radius: var(--border-radius-button);
    @apply font-semibold transition-all duration-300;
  }

  .sw-card {
    @apply rounded-lg bg-white p-6 shadow-md;
  }
}

Responsive Design

Our components are mobile-first and use Tailwind's responsive prefixes:

<div className="sw-container">
  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    {/* Content */}
  </div>
</div>

Form Components

Form elements use our custom styles with Tailwind utility classes:

<form className="space-y-6">
  <div>
    <label className="sw-label">Input Label</label>
    <input 
      className="sw-input w-full focus:ring-sw-blue" 
      type="text"
    />
  </div>
</form>

Styling Guidelines

  1. Using Sport Wales classes:
// Preferred approach using our utility classes
<button className="sw-button sw-button-primary">
  Click Me
</button>

// Custom styling when needed
<div className="sw-card custom-class">
  Content
</div>
  1. Adding custom styles:
/* src/styles/custom/styles.css */
.custom-class {
  /* Your styles here */
}

Deployment Options

Netlify Deployment

  1. Configure netlify.toml:
[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
  1. Deploy:
    • Connect your GitHub repository to Netlify, or
    • Use Netlify CLI: 
      npm install -g netlify-cli
netlify deploy

Railway Deployment

  1. Configure railway.toml:
[build]
builder = "nixpacks"
buildCommand = "npm run build"

[deploy]
startCommand = "npm start"
healthcheckPath = "/"
  1. Use Railway's GitHub integration or CLI for deployment.

Docker Deployment

The template includes a production-ready Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
COPY . .
RUN npm ci
RUN npm run build
EXPOSE $PORT
CMD ["npm", "start"]

Build and run:

docker build -t your-project-name .
docker run -p 3000:3000 your-project-name

Development Workflow

  1. Start development:
npm run dev
  1. Build for production:
npm run build
  1. Preview production build:
npm run preview

Environment Variables

Create a .env file for environment variables:

VITE_API_URL=your-api-url
VITE_OTHER_VAR=other-value

Remember: All variables must be prefixed with VITE_

Best Practices

  1. Component Organisation:

    • Place reusable components in component_library
    • Keep page-specific components in pages
    • Use the Layout component for consistent page structure

  2. State Management:

    • Use React hooks for local state
    • Consider context for shared state
    • Keep state as close to where it's used as possible

  3. Styling:

    • Use Sport Wales utility classes when available
    • Follow the component styling guidelines
    • Maintain responsive design principles

  4. Performance:

    • Lazy load routes and heavy components
    • Optimise images and assets
    • Use appropriate caching strategies

Support and Resources

  • Documentation: Full Sport Wales design system documentation is available in the main repository
  • Support: Contact the Sport Wales development team at [team-email]
  • Issues: Raise issues in the GitHub repository
  • Updates: Check the changelog for template updates

License and Attribution

This project template is proprietary to Sport Wales. All rights reserved.

Important Notes

  • Always prefix environment variables with VITE_
  • Use npm run dev for development
  • The production build is in the dist directory
  • Keep the Sport Wales design system documentation handy
  • Follow the established coding standards and patterns

Need help? Contact the development team or raise an issue in the repository.