You are an expert AI full-stack developer tasked with building a single-page application (SPA) using React and Tailwind CSS. The application, named 'CSS Sihirbazı', aims to empower frontend developers to push the boundaries of modern CSS by creating complex visualizations and interactive experiences, inspired by projects like 'DOOM in CSS'. This tool will serve as both a development utility and a learning platform for innovative CSS techniques.
## PROJECT OVERVIEW:
**Application Name:** CSS Sihirbazı (CSS Wizard)
**Goal:** To provide a user-friendly, AI-enhanced platform for frontend developers to explore, create, and deploy advanced CSS-driven visualizations and interactive experiences. It addresses the challenge of complexity and limitations often encountered when trying to achieve highly performant, visually rich UIs purely with CSS, by offering intuitive tools and learning resources.
**Value Proposition:** Democratize the creation of cutting-edge CSS-based applications (like games, complex UIs, and data visualizations) by simplifying the process, providing powerful tools, and showcasing the immense capabilities of modern CSS. It bridges the gap between creative vision and technical implementation in CSS.
## TECH STACK:
- **Core Framework:** React (using Vite for fast development environment)
- **Styling:** Tailwind CSS (with Headless UI for accessible, unstyled components)
- **State Management:** Zustand (lightweight and performant)
- **Routing:** React Router DOM (for potential future expansion to multiple pages, though MVP is single-page)
- **Animation Library:** Framer Motion (for smooth, declarative animations)
- **Icons:** Heroicons
- **Utility Libraries:** Lodash (for utility functions), clsx (for conditional class names)
## CORE FEATURES:
1. **3D Scene Creator:**
* **User Flow:** Users can enter a 2D/3D canvas. They can add primitive shapes (divs) and position them in 3D space using intuitive controls (sliders for X, Y, Z translation, rotation, scale). Users can apply CSS transforms directly. The tool will visualize the structure and provide the corresponding CSS code.
* **Details:** WYSIWYG editor. Basic shapes: cube, plane. Transform controls: translate (x, y, z), rotate (x, y, z), scale (x, y, z). Ability to assign custom CSS classes and basic styles (background color, border) to elements.
* **Output:** Generates CSS code for transforms, positioning, and basic styling.
2. **CSS Animation & Transition Library:**
* **User Flow:** Users can browse a library of pre-built CSS animations and transitions (e.g., fades, slides, rotations, complex keyframe animations). They can preview these animations on sample elements, customize parameters (duration, easing, delay), and apply them to their created 3D scene objects or as general page effects.
* **Details:** Categories for animations and transitions. Parameter controls (duration, timing function, iteration count, direction). Ability to save customized animations to user's library.
* **Output:** Generates `@keyframes` rules or `transition` property values.
3. **JavaScript Logic Integration Snippets:**
* **User Flow:** For complex interactions or game logic (like in the DOOM example), users need to integrate JavaScript. This feature provides templates and code snippets showing how to manipulate CSS variables, classes, and styles using JavaScript to drive animations or state changes.
* **Details:** Examples of event listeners (click, hover), DOM manipulation for CSS, and controlling CSS variables via JS. Basic game loop structure example.
* **Output:** Copyable JavaScript code snippets.
4. **Responsive Design Preview:**
* **User Flow:** Users can simulate different screen sizes and devices within the application to see how their CSS creations adapt. They can toggle between predefined device views (desktop, tablet, mobile) or use a custom resize option.
* **Details:** Viewport resizing tool. Breakpoint indicators. Basic CSS media query generation suggestions based on layout.
* **Output:** Live preview within the tool.
5. **AI CSS Assistant (Future / Stretch Goal for MVP):**
* **User Flow:** Developers can ask natural language questions about CSS or request code generation (e.g., 'Create a bounce effect for this button', 'Optimize this CSS animation').
* **Details:** Integrates with a language model API to provide CSS suggestions, code snippets, and explanations.
* **Output:** Generated CSS code or explanations.
## UI/UX DESIGN:
- **Layout:** Single-page application. A main canvas/editor area dominates the screen. Sidebars for tools, properties, code preview, and asset library. A top navigation bar for save, export, and settings.
- **Color Palette:** A modern, dark theme with vibrant accent colors (e.g., deep blues, purples, teals for background and UI elements, with bright oranges or cyans for interactive elements and highlights) to reduce eye strain and make the code stand out. Think 'developer's IDE' aesthetic.
- **Typography:** Clean, readable monospace font for code (e.g., Fira Code, JetBrains Mono) and a sans-serif font for UI text (e.g., Inter, Roboto).
- **Responsive Rules:** Mobile-first approach. Sidebars collapse into drawers or menus on smaller screens. Canvas and preview areas adapt dynamically. Ensure usability across devices.
- **Interaction:** Smooth transitions between states, clear visual feedback on hover and click, subtle animations on loading and element appearance.
## COMPONENT BREAKDOWN:
- **`App.jsx`:** Main application component, sets up routing (if needed), layout, and global state.
- **`EditorLayout.jsx`:** Main layout component containing sidebars and the central editor area.
- **`Canvas3D.jsx`:** The core 3D scene rendering component. Handles WebGL/CSS transform rendering. Uses Framer Motion for object manipulation feedback.
- **Props:** `objects` (array of scene objects), `selectedObject` (ID of the currently selected object).
- **`ObjectControls.jsx`:** UI panel for manipulating the selected object's properties (position, rotation, scale).
- **Props:** `selectedObject`, `onUpdateObject`.
- **`TransformSliders.jsx`:** Reusable slider component for controlling X, Y, Z values.
- **Props:** `label`, `value`, `min`, `max`, `step`, `onChange`.
- **`CodePreview.jsx`:** Displays the generated CSS and JS code.
- **Props:** `cssCode`, `jsCode`.
- **`AnimationLibrary.jsx`:** Component to browse, preview, and select animations.
- **Props:** `onSelectAnimation`.
- **`AnimationConfigurator.jsx`:** UI for customizing animation parameters.
- **Props:** `animation`, `onChange`.
- **`ResponsivePreview.jsx`:** Component for simulating different screen sizes.
- **Props:** `children` (the app content to preview).
- **`Sidebar.jsx`:** Container for tool sections (e.g., Object Controls, Animation Library).
- **`Header.jsx`:** Top navigation bar.
## DATA MODEL:
- **`sceneState` (Zustand Store):**
- `objects`: Array of objects, each with properties like `id`, `type` (e.g., 'cube', 'plane'), `position: {x, y, z}`, `rotation: {x, y, z}`, `scale: {x, y, z}`, `style: {backgroundColor, borderColor, ...}`, `className`.
- `selectedObjectId`: String | null
- `currentAnimation`: Object (details of selected animation)
- `animationParameters`: Object (duration, easing, etc.)
- **`mockData` (Example Structure for Scene Object):**
```json
{
"id": "obj-123",
"type": "cube",
"position": {"x": 0, "y": 0, "z": -100},
"rotation": {"x": 0, "y": 45, "z": 0},
"scale": {"x": 50, "y": 50, "z": 50},
"style": {"backgroundColor": "#3b82f6"}, // Tailwind blue-500
"className": ""
}
```
- **`mockData` (Example Structure for Animation):**
```json
{
"id": "fade-in",
"name": "Fade In",
"type": "keyframes",
"config": {
"duration": "1s",
"timingFunction": "ease-in-out",
"iterationCount": "1",
"direction": "normal",
"keyframes": "0% { opacity: 0; } 100% { opacity: 1; }"
}
}
```
## ANIMATIONS & INTERACTIONS:
- **Object Manipulation:** Smooth visual feedback using Framer Motion when dragging, scaling, or rotating objects in the 3D canvas. Bounding box updates in real-time.
- **UI Transitions:** Subtle fades and slides when opening/closing sidebars, panels, or modals. Use Framer Motion for declarative transitions.
- **Loading States:** Skeleton loaders or subtle spinners when loading animations or generating code.
- **Hover Effects:** Gentle scaling or background color changes on interactive elements (buttons, list items) using Tailwind's default or custom hover states.
- **Parameter Changes:** Immediate visual update in the canvas when sliders or input fields are adjusted.
## EDGE CASES:
- **Empty State (Canvas):** Display a helpful message and clear instructions when no objects are present in the scene. Provide a button to add the first object.
- **Empty State (Code Preview):** Display placeholder text or a message when no code has been generated yet.
- **Error Handling:** Gracefully handle potential errors during code generation or rendering. Display user-friendly error messages. For example, if an invalid CSS value is entered.
- **Validation:** Input validation for numerical fields (position, scale, duration) to ensure they are within reasonable ranges. Prevent non-numeric input where applicable.
- **Accessibility (a11y):** Use semantic HTML. Ensure interactive elements are focusable and have clear focus states. Use ARIA attributes where necessary, especially for custom controls and state indicators. Ensure sufficient color contrast. Use Headless UI for accessible component primitives.
## SAMPLE DATA:
1. **Initial Scene Object (Cube):**
```json
{
"id": "obj-1",
"type": "cube",
"position": {"x": 0, "y": 0, "z": -50},
"rotation": {"x": 0, "y": 0, "z": 0},
"scale": {"x": 100, "y": 100, "z": 100},
"style": {"backgroundColor": "#6366f1"}, // Indigo-500
"className": ""
}
```
2. **Second Scene Object (Plane):**
```json
{
"id": "obj-2",
"type": "plane",
"position": {"x": 0, "y": -50, "z": 0},
"rotation": {"x": -90, "y": 0, "z": 0},
"scale": {"x": 200, "y": 200, "z": 1},
"style": {"backgroundColor": "#94a3b8"}, // Slate-400
"className": ""
}
```
3. **Pre-built Animation (Slide In Left):**
```json
{
"id": "slide-left",
"name": "Slide In Left",
"type": "keyframes",
"config": {
"duration": "0.8s",
"timingFunction": "cubic-bezier(0.25, 0.46, 0.45, 0.94)",
"iterationCount": "1",
"direction": "normal",
"keyframes": "0% { transform: translateX(-100%); opacity: 0; } 100% { transform: translateX(0); opacity: 1; }"
}
}
```
4. **Pre-built Transition (Color Change):**
```json
{
"id": "color-change",
"name": "Color Change on Hover",
"type": "transition",
"config": {
"property": "background-color",
"duration": "0.5s",
"timingFunction": "ease",
"delay": "0s"
}
}
```
5. **JS Snippet Example (Toggle Class on Click):**
```javascript
document.getElementById('obj-1').addEventListener('click', () => {
document.getElementById('obj-1').classList.toggle('animate-bounce');
});
```
6. **CSS Variable Example:**
```css
/* In CSS */
.my-element {
transform: translateX(var(--custom-x, 0px));
transition: transform 0.3s ease;
}
/* In JS */
const element = document.getElementById('my-element');
element.style.setProperty('--custom-x', '50px');
```
7. **Default Transform State:**
```json
{
"position": {"x": 0, "y": 0, "z": 0},
"rotation": {"x": 0, "y": 0, "z": 0},
"scale": {"x": 1, "y": 1, "z": 1}
}
```
8. **Empty Scene State:**
```json
{
"objects": [],
"selectedObjectId": null,
"currentAnimation": null
}
```
## DEPLOYMENT NOTES:
- **Build Tool:** Vite is recommended for its speed and ease of configuration.
- **Environment Variables:** Use `.env` files for API keys (if any) or configuration settings. Prefix variables with `VITE_` for Vite.
- **Performance Optimizations:**
- Code Splitting: Vite handles this automatically for routing if expanded.
- Image Optimization: If images are used, ensure they are optimized.
- Memoization: Use `React.memo` for components that re-render unnecessarily.
- State Management: Keep state updates efficient. Avoid unnecessary re-renders by structuring the Zustand store effectively.
- **Hosting:** Static hosting platforms like Vercel, Netlify, or GitHub Pages are suitable for SPAs.
- **Build Command:** `npm run build` (or `yarn build`).
- **Development Server:** `npm run dev` (or `yarn dev`).