New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README.md not clear enough #151

Open
edwinm opened this Issue May 27, 2016 · 9 comments

Comments

Projects
None yet
8 participants
@edwinm
Copy link

edwinm commented May 27, 2016

I you've never heard of CSS Modules (like me) and you read README.md, the questions only stack up.

"A CSS Module is a CSS file in which all class names and animation names are scoped locally by default." - Scoped? To what? How? Is it auto generating BEM notation? What is the prefix? The folder name?

"CSS Modules compile to a low-level interchange format called ICSS or Interoperable CSS" - Why do you want to do that?

"When importing the CSS Module from a JS Module" - Why would you want to import CSS from JavaScript?

Please start your README.md with the problem it is solving en preferably an example.

@mikeerickson

This comment has been minimized.

Copy link

mikeerickson commented May 27, 2016

+1

Having agreed, lets remember this is OSS so have some compassion.

@edwinm

This comment has been minimized.

Copy link

edwinm commented May 27, 2016

I'm fully aware :-) I did not intent to sound harsh.

@joshwnj

This comment has been minimized.

Copy link
Member

joshwnj commented May 30, 2016

Thanks @edwinm it's great to hear questions like this so that we can communicate the ideas better :)

"A CSS Module is a CSS file in which all class names and animation names are scoped locally by default." - Scoped? To what? How? Is it auto generating BEM notation? What is the prefix? The folder name?

Would you find it clearer if we said "A CSS Module is a CSS file in which all class names and animation names are prefixed to make them globally unique" ?

"When importing the CSS Module from a JS Module" - Why would you want to import CSS from JavaScript?

Maybe this would be clearer as "When importing the CSS Module into a JS Module". What do you think?

@edwinm

This comment has been minimized.

Copy link

edwinm commented May 30, 2016

@joshwnj Please start with describing which problem CSS Modules is solving. Add a little code example. Show the problem without CSS Modules and show the fix by using CSS Modules.

@neekey

This comment has been minimized.

Copy link

neekey commented Jun 3, 2016

+1, the whole idea seems cool, but the documentation does not make much sense to me.

@neekey

This comment has been minimized.

Copy link

neekey commented Jun 3, 2016

after reading @markdalgleish 's amazing article, it makes more sense to me now: https://medium.com/seek-ui-engineering/the-end-of-global-css-90d2a4a06284#.ow8bnkjh4

I guess the documentation need to bring out some background knowledge for those ( like me ) didn't know much about "local scope css"

@kevnk

This comment has been minimized.

Copy link

kevnk commented Jun 6, 2016

Does this count for documentation? https://github.com/ruanyf/css-modules-demos

If not, what other details do you still need?

@100ideas

This comment has been minimized.

Copy link

100ideas commented Jun 8, 2016

CSS-tricks has an article (3-part series) that goes into more detail about CSS Modules and how they work with webpack.

I was confused too - my experience level seems to be too low for me to successful decipher the mysterious vagaries in the Implementations > Webpack section at the bottom of the readme. Extending? What sorcery is this?!

"Extending adds the source class name(s) to the exports."

"Extending from other modules first imports the other module and then adds the class name(s) to the exports."

I assume it has to do with extending react components?

export default class LandingSection extends React.Component {
    static propTypes = {
        children: React.PropTypes.element,
        postContent: React.PropTypes.element,
        title: React.PropTypes.string.isRequired,
    };
//...
@dvkndn

This comment has been minimized.

Copy link

dvkndn commented Sep 15, 2016

I think we should also have an example code on README to show how the "scoped" classes will look like, like in the section about css module on postcss website:

/* input */
.name {
  color: gray;
}
/* output */
.Logo__name__SVK0g {
  color: gray;
}

and another one to show how the returned object looks like

import styles from 'logo.css';
// styles = { 'name': 'Logo__name__SVK0g' }

it would help people to understand how CSS Module really work..

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment