Doc / guideline for 1.0 customization

deneuxa commented 10 years ago

Hello @jack, I'm trying to switch to the CSS branch (which correspond to WIP 1.0 right?).

I'm not very sure of how to set up the whole thing. I noticed some typos in the readme too :

Installing Semantic 1) You must rename your user folder from /themes/.user to themes/user to avoid library updates modifying your site's settings => /themes/.user don't exist in SRC directory, I guess it is /themes/_user

2) Rename your semantic config file from 'semantic.config.example' to 'semantic.config' => OK, but there was yet a 'semantic.config', it should be removed no ? Next update would overide it ?

Customizing Semantic 1) Default variables are stored in themes/default. 2) To use a theme. Unzip the theme and its its contents to theme/packaged/. Some themes are included with the default package to get you started. 3) You can also specify custom overrides for themes specific to your site these are stored in themes/site

1) To build your project you must rename some folder => should be step 4 right?

OK so now I'm not sure how to set up the whole thing :

should I rename site.less to alexis.less too? -what happened with awesome font ? Will you remove it from the default theme ?
where should I set my own variables ? In theme/alexis/site.variables or theme/alexis/site.overrides. I understand both will work but what'is the way to go ?

I'm a bit lost. Let's take a simple example. If I want to change the color of the red button. Should I : 1) change the value of @backgroundColor in theme/default/elements/button.variables (I guess no) 2) set a new value for @backgroundColor in theme/default/elements/button.overrides (I guess no) 3) set a new value for @backgroundColor in theme/alexis/elements/button.variables 4) set a new value for @backgroundColor in theme/alexis/elements/button.overrides 5) should I : a) let declared in semantic.config @button : 'default'; b) or should I change it for @button : 'alexis';

I guess if I change the whole button settings I should go for option b) but if I only change the color I should go for a), am I right ?

Thanks for your help !

jlukic commented 10 years ago

This is all really new but I'll explain the current thought process.

Setting up Semantic

1) Yes user overrides exist in _site aka site not .user. This was renamed to make more sense for the web.

In Sublime and installed programs user settings are typically referred to as user overrides, but on the web it makes more sense to think of it as site overrides since they correspond to customizations for a particular site.

Folders with . names are not allowed in windows file systems so it was swapped for _site

2) Yes, semantic.config shouldn't be in the repo, but for the moment it is currently included because not including it causes all Travis CI tests to break as the LESS doesn't compile correctly on Travis CI without a config file.

In the future I will find a workaround for this by customizing Travis CI but i need the tests to run now, so for now it is temporarily committed.

Customizing Semantic

I'll try to explain variable inheritance by example.

Using a default theme

Lets say you leave button theme to default. There are two levels of inheritance in this example

1) themes/default/elements/button.variables loads the UI variables 2) themes/packaged/default/elements/button.variables loads a blank file 3) themes/sites/elements.button.variables loads your overrides for variables

Using a packaged theme

Lets say you change button theme to chubby. There are three levels of inheritance in this example

1) themes/default/elements/button.variables loads the UI variables 2) themes/packaged/chubby/elements/button.variables loads the "downloadable" theme (this will allow for community packages) In this example, a button theme called chubby 3) themes/sites/elements.button.variables loads your overrides for variables

The same three levels occur for override files.

On Packaged Themes

You can browse currently available themes by looking in themes/packaged. There is also now a dropdown in the docs for viewing different themes. I'd recommend checking the button page for an example of an element with several themes.

Adjust your site's configuration

To customize a ui button you can

Add variable overrides in site/elements/button.variables
Add user LESS/CSS overrides in /site/elements/button.overrides (this will have all variables accessible)

Semantic now also includes some site-wide configuration by default in site.less it is recommended you include this also. Semantic now requires a box-sizing reset this allows us more flexibility inside the framework to not deal with issues related to calculating padding. This is included in site.less as well as a standard HTML reset.

Tips

There is only one folder you should ever edit files in themes/site.

Files in themes/packaged are downloaded from the web or a package manager, and themes/default are part of the core library.

It's best when adding variables to your site's configuration to look at themes/default to see what variables can be modified. These files are all blank until you add your own variable overrides.

Keep in mind this is being committed to near daily, the branch is currently in a stable place, but there will be days when it is not.

jlukic commented 10 years ago

I'm going to do a little housekeeping on this today, so I recommend waiting till end-of-day for the results.

Will be adding some automation with grunt and moving globals to be less confusing

deneuxa commented 10 years ago

Thanks for yours answers;

I can't see the dropdown theme-switcher in the button page. Are u talking about www.semantic-ui.com or about the local generated doc (which I neveer used :) )

-what about font awesome ? : will it be dropped in 1.0 ?

I understood the system of variable overriding, but maybe is it too much ? each variable can be overidded in overide or variable files and in many differents places.
the main problem I'm facing is that none of my variables work : I even tried to replace some values directly in the defaut's theme. I think it's because of Rails pipeline system. I asked to @nd0ut (https://github.com/nd0ut/semantic-ui-rails/issues/21) if he tried something yet.

jlukic commented 10 years ago

I've updated the readme and folder structure in css branch, it should now be as easy as running grunt to build the project. Or you can use whatever tools you normally use.

The only way to see the new versions of UI elements is to run the docs locally, since its not launched yet and is not available online.

deneuxa commented 10 years ago

Far better, many thanks ! I get it worked nicely now and perfectly understood the logic of variables overides and stuff.

I only still got 2 problems : 1) rails's pipeline doesn't load correctly the variables and have to delete all cache after every modification; but it's a rails's problem of course 2) local doc is soooOO slow. I can get the index page quickly, but have to wait like 3 minutes for viewing the button page and every others page. It's strange. I guess it's not a SUI problem either.

Jack the job you've done with themes and SUI customization is just awesome :) the possibility of customizing asset's path will be a huge avantage for many frameworks integration

I'll attempt to use pre-1.0 for my current project (going to production in 1 month I guess)

2 remarks :

the new reset.less seems to me a very good thing, but it broke a lot of things.
It seems to me that 1.0 will come with some important deprecations, so maybe we can think about the changes I made with icons (which come with some deprecations too) ? The most important thing is I think the rename of Sui's icons "square" class by "squared". It's more coherent with 'inverted' or 'rotated' or 'flipped' and it allow to use all the FontAwesome 'square' classes. let me know if you plan to include it soon or if I re-apply my modifications locally in my site/elements/icons.overrides ;)

deneuxa commented 10 years ago

Another thing : is there any reason that xxx.overrides and xxx.variables aren't named xxx.overrides.less and xxx.variables.less ?

the miss of the less extension doesn't allow rich editor to preview color and stuffs.

jlukic commented 10 years ago

You can set default syntax highlighting for any extension in sublime text

Docs re-render for me in 3 seconds, grunt updates in 0.5s. All negligible. This is on a laptop as well.

I prefer keeping things to one extension, renames with grunt get messy with multiple dots. There are plenty of deprecations in 1.0, icon updates can be one of them.

deneuxa commented 10 years ago

I'm not using sublime text

I solved my problem with the dox, it's now fast. Another question : how could I fully override a single element ?

If I can change a full element in semantic.config by one of another theme, but I think I can't do this by one of my site folder directly.

/* To override a theme for an individual element specify theme name below Be sure to update the user folder name (see README) */

/* Global */ @site : 'default'; @reset : 'default';

/* Elements */ @button : 'default'; @container : 'default';

jlukic commented 10 years ago

Overrides for an elements go in /themes/site/type/name.overrides

i.e. themes/site/elements/button.overrides

If you want to create a theme package, give it a name, put it in themes/packaged/yourtheme/ and specify the theme in semantic.config

@button: 'yourtheme';

deneuxa commented 10 years ago

OK it's what I understood, it could have been great of replacing a full element (not override it because it could create some conflicts) without creating a theme.

My actual case was to replace the default icon element by my own, but if I override it, I still inherit some classes of the default theme. I was looking for a way to do this without creating my own theme.

It would be nice if semantic.config could understand that when i replace 'default' by 'site' for an element, it means to take the site element and not a theme named 'site'.

2014-03-04 17:21 GMT+01:00 Jack Lukic notifications@github.com:

Overrides for an elements go in /themes/site/type/name.overrides

i.e. themes/site/elements/button.overrides

If you want to create a theme package, give it a name, put it in themes/packaged/yourtheme/ and specify in semantic.config

@button: 'yourtheme';

— Reply to this email directly or view it on GitHubhttps://github.com/Semantic-Org/Semantic-UI/issues/675#issuecomment-36642355 .

jlukic commented 10 years ago

Anything you include in site overrides will be included after defaults, these will override any css included in core library.

If you don't need any rules from semantic, then you can create your css outside of the framework, there would be no purpose in using it to begin with.

tmikaeld commented 10 years ago

I just read this thread and i felt compelled to add that i also believe .less is standard and least prone to compatibility problems in different editors.

If you want to keep the double naming, use "-" instead like this: button-overrides.less

I loved this UI/Framework kit, but how mature / tested is it, are anyone using it in production? I'm not that keen on using bootstrap nor foundation 5 - SUI seems much more thought through.

deneuxa commented 10 years ago

Hello I'm going to production with SUI this week ;) I'll tell you what !

2014-03-17 16:25 GMT+01:00 tmikaeld notifications@github.com:

I just read this thread and i felt compelled to add that i also believe .less is standard and least prone to compatibility problems in different editors.

If you want to keep the double naming, use "-" instead like this: button-overrides.less

I loved this UI/Framework kit, but how mature / tested is it, are anyone using it in production? I'm not that keen on using bootstrap nor foundation 5 - SUI seems much more thought through.

— Reply to this email directly or view it on GitHubhttps://github.com/Semantic-Org/Semantic-UI/issues/675#issuecomment-37828371 .

Anachron commented 10 years ago

Please don't forget to document the changes done here: https://github.com/Semantic-Org/Semantic-UI/pull/601

tmikaeld commented 10 years ago

semantic.config import directives makes no sense to me.

The import: @import "@{packagesFolder}/default/globals/site.variables";

Points to folder: /themes/packages/default/globals/site.variables

That file doesn't even contain @type variable

But this file do: /definitions/globals/site.less

Is this where the import is supposed to point to?

EDIT: Pointing it there would create a loop.

I'm tired of waiting so i'll just include the less-files manually for now.

Semantic-Org / Semantic-UI