Documentation

[ Internal Wiki & Contributor Guides ]

>_ [DOC: 01]

SUDATA Website

Welcome to the repository for the SUDATA website. This project is built with Astro, React, and Tailwind CSS, designed with a high-fidelity "Cyberpunk/Retro" aesthetic.

Tech Stack

Framework: Astro
UI Library: React
Styling: Tailwind CSS
Icons: pixelarticons
3D/Graphics: Three.js / React Three Fiber

Getting Started

Clone the repository
Install dependencies:
```
npm install
```
Run the development server:
```
npm run dev
```
Access the site at http://localhost:4321.

Design System & recent Updates

We have recently overhauled the UI to ensure a unified visual identity. Please adhere to the following guidelines when contributing.

1. Color Palette

Neon Blue (Primary): #00F0FF (Used for text glows, icons, borders, and active states).
Deep Navy (Background): #020617 (Main background).
Grey (Text): #94a3b8.

2. Iconography (`pixelarticons`)

We have migrated to pixelarticons for all glyphs to maintain a retro 32-bit feel.

Usage: Embed SVG paths directly or import if available.
Rendering: ALWAYS apply style="image-rendering: pixelated;" to SVGs to prevent blurring at larger scales.
Styling:
- Fill: #00F0FF (Electric Blue) or #020617 (Navy) for contrast on blue buttons.
- Glow: filter: drop-shadow(0 0 10px #00F0FF); for neon elements.
Exceptions:
- Instagram Icon: The standard package version may lack the Instagram logo. A custom pixel-art SVG path has been implemented in index.astro.
- Brain Icon: A custom high-def pixel brain is used for "The Hub".

3. Glass Slabs (Knowledge Hub)

Interaction: Cards lift vertically (translateY(-20px)) and scale (1.05) on hover.
Visuals: Use backdrop-blur-2xl and a deep blue outer glow on hover.
Animation: Elements use a scroll-driven intersection observer with a "heavy" mechanical easing (cubic-bezier(0.16, 1, 0.3, 1)).

Development Notes & Missing Items

Things team members should be aware of:

Missing Icons: Not all icons are present in the installed pixelarticons version (v1.8.1). If you need a specific brand icon (e.g., Discord, LinkedIn), you may need to manually create a pixel-perfect SVG path or find a compatible retro alternative.
Performance: The heavy usage of backdrop-blur and box-shadow glows can be performance-intensive on lower-end devices. Future optimization may be needed.
Accessibility:
- Ensure contrast ratios are maintained, especially with neon text on dark backgrounds.
- Action Item: SVGs currently lack proper aria-label or title tags. These should be added for screen readers.
Mobile Responsiveness: While the grid collapses to a single column, the large 96px icons and glass padding should be tested on very small screens (iPhone SE, etc.) to ensure no overflow.
3D Elements: The NetworkLogo component relies on client-side React hydration (client:only="react"). Ensure Three.js context is handled correctly to prevent memory leaks during hot reloads.

Project Structure

/
├── public/
│   ├── favicon.svg      # Site icon
├── src
│   ├── assets/          # Static assets (SVGs, images)
│   ├── components/      # React & Astro components (NetworkLogo, etc.)
│   ├── layouts/         # Main layout wrapper (Layout.astro)
│   ├── pages/           # Route pages (index.astro)
│   └── styles/          # Global CSS (Tailwind imports, custom animations)
└── package.json

>_ [DOC: 02]

Events Calendar

Scripts

Events page — fill in src/data/events_template.xlsx, then convert:

python3 scripts/convertExcelToJson.py src/data/events_template.xlsx src/data/events.json

Careers/Sponsorships page — fill in src/data/opportunities_template.xlsx, then convert:

python3 scripts/convertOpportunitiesExcelToJson.py src/data/opportunities_template.xlsx src/data/opportunities.json

events.json field reference

{
  "id": "event_001",
  "title": "Python Workshop",
  "date": "2025-03-15",
  "time": "18:00",
  "venue": "Computer Lab 3B",
  "type": "academic",
  "description": "Learn Python basics and data manipulation",
  "collaborators": ["SUDATA", "CS Department"],
  "catering": "Pizza and drinks",
  "signupLink": "https://forms.google.com/...",
  "attendees": 45
}

date: YYYY-MM-DD
time: 24-hour format (e.g. 18:00)
type: must be exactly academic, social, or industry
collaborators: array (e.g. ["Org1", "Org2"])

>_ [DOC: 03]

Yearly Calendar Updates

Run once per year when USyd releases the new academic calendar (usually November).

Download the PDF from https://www.sydney.edu.au/students/key-dates.html

1. Update `src/data/semesterDates.js`

Add a new year block using dates from the PDF:

export const SEMESTER_DATES = {
  // ... existing years ...

  2027: {
    semester1: {
      welcomeProgram: { start: '2027-02-XX', end: '2027-02-XX' },
      teaching: { start: '2027-02-XX', end: '2027-05-XX' },
      censusDate: '2027-03-XX',
      midSemesterBreak: { start: '2027-04-XX', end: '2027-04-XX' },
      stuvac: { start: '2027-06-XX', end: '2027-06-XX' },
      exams: { start: '2027-06-XX', end: '2027-06-XX' }
    },
    semester2: {
      welcomeProgram: { start: '2027-07-XX', end: '2027-08-XX' },
      teaching: { start: '2027-08-XX', end: '2027-11-XX' },
      censusDate: '2027-08-XX',
      midSemesterBreak: { start: '2027-09-XX', end: '2027-10-XX' },
      stuvac: { start: '2027-11-XX', end: '2027-11-XX' },
      exams: { start: '2027-11-XX', end: '2027-11-XX' }
    }
  }
};

PDF to config mapping

PDF says	Config field
"Welcome Program: Feb 10-21"	`welcomeProgram: { start: '2025-02-10', end: '2025-02-21' }`
"Teaching weeks: Feb 24 - Jun 1"	`teaching: { start: '2025-02-24', end: '2025-06-01' }`
"Census date: 31 March"	`censusDate: '2025-03-31'`
"Mid-semester break: 21-27 April"	`midSemesterBreak: { start: '2025-04-21', end: '2025-04-27' }`
"Study vacation (STUVAC): 2-8 June"	`stuvac: { start: '2025-06-02', end: '2025-06-08' }`
"Examinations: 10-21 June"	`exams: { start: '2025-06-10', end: '2025-06-21' }`

All dates use YYYY-MM-DD format.

2. Add year to `src/components/EventCalendar.jsx`

const availableYears = [2024, 2025, 2026, 2027]; // add new year here

3. Update `src/data/publicHolidays.js` (only if API fetch fails)

NSW public holidays: https://www.industrialrelations.nsw.gov.au/public-holidays/

export const PUBLIC_HOLIDAYS = {
  // ... existing years ...

  2027: [
    { date: '2027-01-01', name: "New Year's Day" },
    { date: '2027-01-26', name: 'Australia Day' },
    // ... remaining holidays
  ]
};

>_ [DOC: 04]

Managing and Adding Photo Albums

Photo Albums can be easily added by any team member.

Firstly, photos must be numbered incrementally and stored in the assets/albums/ directory. To rename all images to be incrmemental (01.jpg, 02.jpg, ...), run the rename_inc.py script and pass the album directory as a command-line argument. After a little bit (O(n) complexity where n=# of images), all images will be named accordingly.

Now, in the photos.astro file in the pages/ directory, import the album as follows:

const albumGlob = import.meta.glob("../assets/albums/albumName/*.{jpg,jpeg,png,webp,avif}", {
  eager: true,
  import: "default",
});

This loads all the images in the directory (caching todo).

Next, add the album metadata to the albums array, for example:

const albums = [
  {
    name: "INN 2025",
    date: "May 2025",
    images: loadAlbum(innGlob, "INN 2025"),
    link: "https://photos.app.goo.gl/sPAGscihAqiscHNU6"
  },
]

Ensure to add the Google Photos album link (with SUDATA Tech account) and uncheck the Collaborate option when you fetch the share link.

Thats it! The rest is handled via array iteration.

>_ [DOC: 05]

Pie Chart Data

The About page displays four membership demographic charts (Field, Degree, Gender, Ethnicity) populated from a CSV file. Place an updated sudata_members_cleaned.csv in src/data/ with the exact column names below and the charts will reflect the new data on the next build.

src/utils/processChartData.js expects these EXACT column names:

major_std (for Field Distribution chart)
degree_std (for Degree Distribution chart)
gender (for Gender Balance chart)
ethnicity_std (for Ethnicity Diversity chart)